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Preface 


J2ME™ Personal Profile (Personal Profile) includes the full Java™ programming 
language with a runtime environment optimized for devices that need a small 
footprint, such as PDAs. The goal of Personal Profile is to bring many of the 
benefits of Java software programming to the resource-constrained world of small 
devices. Personal Profile is part of Java™ 2 Platform, Micro Edition J2ME™ 
technology). It includes a subset of the APIs in Java™ 2 Platform, Standard Edition 
(J2SE™ technology). 


The Personal Profile API has been approved by the Java Community Process (JCP), 
in Java Specification Request (JSR) 62. It can support many graphics library 
specifications and APIs, such as Home Audio-Video interoperability (HAVi), DVB 
Multimedia Home Platform (MHP), and the Java TV™ API. 


Who Should Use This Guide 


This guide contains tips and guidelines for programmers developing applications, 
applets, Xlets, graphics libraries, and APIs with the Personal Profile API. 


Before You Read This Guide 


Before reading this guide, you should be familiar with the Java programming 
language, object-oriented design, the Personal Profile specification, and the J2ME 
Platform, including Connected Device Configuration (CDC) and Foundation 
Profile, Version 1.0.1. If you are trying to develop an application for a specific 
device, you might also need to be familiar with any specifications and APIs you 
want to be compatible with, such as HAVi, DVB MHP, Java TV API, and so on. 


xi 


A good resource for becoming familiar with Personal Profile is the Sun 
Microsystems, Inc. website, located at http: //java.sun.com/products/ 
personalprofile. 


How This Guide Is Organized 


Chapter 1, “Introducing Personal Profile,” provides an overview of Personal 
Profile. 


Chapter 2, “Running the Sample Programs,” tells you how to run the samples. 


Chapter 3, “Writing Applications,” describes the basics of writing an application 
that uses Personal Profile. 


Chapter 4, “Writing Applets,” describes the basics of writing an applet that uses 
Personal Profile. 


Chapter 5, “Writing Xlets” describes the basics of writing an Xlet that uses Personal 
Profile. 


Chapter 6, “Writing Xlet Managers,” describes the basics of writing an Xlet 
Manager that uses Personal Profile. 


Chapter 7, “Understanding Personal Profile Packages, Classes, and Interfaces,” 
orients you to the Personal Profile API and lists deprecated methods that were 
removed. 


Chapter 8, “Implementing Common Programmatic Features,” describes common 
tasks you might need to implement with Personal Profile. 
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Chapter 9, “Using the Reference Implementation as a Development Platform,’ 
describes how to compile, run, and debug applications, applets, and Xlets. 


Chapter 10, “Comparing Personal Profile and the PersonalJava Environment,” 
compares Personal Profile and the PersonalJava environment. 


Related Specifications 


The official Personal Profile, CDC, and Foundation Profile specifications are located 
at the Java Community Process (JCP) website for Java Specification Requests (JSRs) 
#62, #36, and #46. These represent the only official versions of the specifications. 
Specifications generated from the source files in the Personal Profile, CDC, and 
Foundation Profile implementations are not valid. 
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Note — Do not rely on the Javadoc™ files generated from the source files in the 
reference implementation. Use the official specification's Javadoc files instead. 


J2ME™ Personal Profile (Personal Profile) Specification, JSR-62 - http: // 
www. jcp.org/jsr/detail/062.jsp 


Personal Basis Profile Specification, JSR-129 - http: //jcp.org/jsr/detail/ 
123. jsp 

CDC Specification, JSR-36 - http://jcp.org/jsr/detail/036. jsp 
Foundation Profile Specification, JSR-46 - http: //jcp.org/jsr/detail/ 
046.jsp 

J2ME Platform Specification, JSR-68 - http://www. jcp.org/jsr/detail/ 
068. jsp 


J2ME™ RMI Optional Package (RMI OP) Specification, JSR-66 - for remote 
method invocation at http://www. jcp.org/jsr/detail/066. jsp 


Related Literature 


For more information about this release of Personal Profile, see the Release Notes 
and Porting Notes, J2ME™ Personal Profile, Version 1.0 included with this product. 


A good resource for becoming familiar with Java technology is the Sun 
Microsystems, Inc. website, located at http: //java.sun.com. 


In addition, the following documents and web pages might also be of interest: 


Java 2 Platform, Micro Edition J2ME technology) at http: //java.sun.com/ 
products/j2me 


Java 2 Platform, Micro Edition (J2ME™) Technology for Creating Mobile Devices, A 
White Paper, Sun Microsystems, Inc., see http: //java.sun.com/products/ 
4j2me/ 


Introduction to Wireless Java™ Technology at http: // 
wireless. java.sun.com/getstart/ 
Java™ 2 Platform, Standard Edition (J2SE™ technology) at http: // 


java.sun.com/products/j2se 


CDC and Foundation Profile information: Porting Guide, Connected Device 
Configuration and Foundation Profile, Version 1.0.1 at http: //java.sun.com/ 
products/cdc 


CDC whitepaper at http: //java.sun.com/products/cdc/wp/CDCwp.pdf 


Foundation Profile information at http: //java.sun.com/products/ 
foundation/ 


Gnome Tookit (GTK+), graphical windowing environment information at 
http://www.gtk.org 
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a Java Community Process™ at http: / 7 jep.org 
a Java TV™ Technology's Place in Enhanced and Interactive Television at http: // 
servlet.java.sun.com/javaone/javaone2000/pdfs/TS-1044. pdf 


a Television Futures - Java TV™ Technology Looms Large at http: // 
developer. java.sun.com/developer/technicalArticles/javatv/ 
overview/index.html 


a Introduction to Digital TV Applications Programming at http: // 
developer. java.sun.com/developer/technicalArticles/javatv/ 
apiintro/ 

a Java TV™ API Technical Overview: The Java TV API Whitepaper at http: // 
java.sun.com/products/javatv/jtv—-1_0-spec_overview. pdf 

a Java TV Technology Home Page at http: //java.sun.com/products/ 
javatv/ 

= RMI OP information at http: //java.sun.com/products/jdk/rmi/ 


= Connected, Limited Device Configuration Specification, version 1.0, Java Community 
Process, Sun Microsystems, Inc. at http: //java.sun.com/aboutJava/ 
communityprocess/jsr/jsr_030_j2melc.html 


= Portable Operating Systems Interface (POSIX) catalog at http: // 


standards.ieee.org/catalog/posix.html 


m The Standard C Library at http: //www.prenhall.com/books/ 
per_o131315099.htm1, 


a The Java™ Language Specification (Java Series), Second Edition by James Gosling, 
Bill Joy, Guy Steele and Gilad Bracha. Addison-Wesley, 2000, ISBN 0-201-31008- 
2,and at http://java.sun.com/docs/books/jls/index.html 


a The Java™ Virtual Machine Specification (Java Series), Second Edition, by Tim 
Lindholm and Frank Yellin. Addison-Wesley, 1999, ISBN 0-201-43294-3and at 
http://java.sun.com/docs/books/vmspec/index.htm1l 


a The Java™ Programming Language (Java Series), Second Edition by Ken Arnold and 
James Gosling (Addison-Wesley, 1998). 


a The Java Class Libraries: An Annotated Reference, Second Edition (Java Series) by 
Patrick Chan, Rosanna Lee and Doug Kramer (Addison-Wesley, 1999) 


a The Java Software website, with the latest information on Java technology, 
product information, news, and features at http: //java.sun.com/ 


a Java Platform Documentation provides access to whitepapers, the "Java Tutorial’ 
and other documents at http: //java.sun.com/docs 


a The Java Developer Connection website at http://java.sun.com/jdc 
a Java Technology Products and APIs at http: //java.sun.com/products/ 
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What Typographic Changes Mean 


The following table describes the typographic changes used in this guide. 


Typeface or 


Symbol Meaning Example 

AaBbCc123 The names of commands, files, Edit your .1login file. 

or items of source code, and Use ls -a to list all files. 

classes directories; on-screen computer machine_name% You have mail. 
output. 

AaBbCc123 Command-line placeholder: To delete a file, type rm <filename>. 


replace with a real name or 
value. Also, book titles, new 
words or terms, or words to be 
emphasized. 


Brackets. The option or 
argument enclosed in these 
brackets is optional. If the 
brackets are omitted, the 
argument must be specified. 


Ellipses. Several values can be 
provided for the previous 
argument, or the previous 
argument can be specified 
multiple times, for example, 
"filename..." . 


Separator. Only one of the 
arguments separated by this 
character can be specified at a 
time. 


Braces. The options and/or 
arguments enclosed within 
braces are interdependent, such 
that everything enclosed must 
be treated as a unit. 


Read Chapter 6 in User’s Guide. These 
are called class options. 
You must be root to do this. 


-args argl [arg2] 
-args argl [arg2] [arg3] 
-path Path | —codebase URL 


cvm com.sun.xlet.XletRunner 
{-name XletName {-path Path 
-codebase URL} [-args argl 
[arg2] [arg3] ...]} 


Using UNIX Commands 


This document may not contain information on basic UNIX® commands and 
procedures such as shutting down the system, booting the system, and configuring 


devices. 
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See one or more of the following for this information: 

a Solaris Handbook for Sun Peripherals 

a AnswerBook2™ online documentation for the Solaris™ operating environment 
a Other software documentation that you received with your system 


Accessing Sun Documentation Online 


The docs. sun.com*™" website enables you to access Sun technical documentation 
on the Web. You can browse the archive at http: //docs.sun.com or search for a 
specific book title or subject at http: //developer. java.sun.com/ 
developer/infodocs/. 


Sun Welcomes Your Comments 


We are interested in improving our products and documentation and welcome 
your comments. You can email your Personal Profile comments to us at: 


j2me-pp-comments@sun.com 


xvi Personal Profile Programmer’s Guide + September 2002 


CHAPTER 1 


Introducing Personal Profile 


J2ME Personal Profile provides a powerful application environment for creating 
compact applications, useful for networked, resource-constrained devices, and can 
serve as the basis for custom toolkits and APIs. This chapter describes Personal 
Profile architecture and uses, and how it fits in with other technologies, in the 
following sections: 


a “What Is Personal Profile?” on page 1 

a “Specifications that Personal Profile Can Support” on page 3 

a “Compatibility With Other Specifications” on page 4 

a “Examples of Possible Implementations that Use Personal Profile” on page 4 
a “Product Architecture and Requirements” on page 5 

a “Advantages of Personal Profile” on page 7 

a “Three Application Models” on page 7 

a “Comparison of Personal Profile Applications, Applets, and Xlets” on page 9 
a “Comparison of Personal Profile Xlets and Other Xlets” on page 10 

a “Development with Reference Implementation Packages” on page 10 


What Is Personal Profile? 


Personal Profile provides a Java 2 Platform, Micro Edition (J2ME Platform) 
application environment for network-connected devices. It provides full Abstract 
Window Toolkit (AWT) support (relative to JDK 1.1 AWT) and includes a number 
of feature improvements introduced by J2SE. Personal Profile provides a platform 
for the development of Java applications for consumer electronics devices. Personal 
Profile provides much of the functionality of the PersonalJava environment, but in 
a next-generation J2ME profile. 


As its name implies, Personal Profile is a J2ME profile: a collection of Java 
technology-based class libraries and APIs and a specific configuration that 
provides domain-specific capabilities for devices in a specific vertical market. A 
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profile is an additional way of specifying the subset of Java APIs, class libraries, 
and virtual machine features that targets a specific family of devices. Personal 
Profile is highly suitable for markets such as the high-end PDA space, web tablets, 
and vertical application devices. The profile serves as a suitable platform for web 
applets and as a J2ME migration path for PersonalJava applications. 


Personal Profile applications can be graphical or non-graphical. Graphical 
applications are based on AWT, including heavyweight and lightweight 
components. Personal Profile provides a heavyweight AWT toolkit. This compares 
to Personal Basis Profile which provides basic AWT support but excludes support 
for the AWT heavyweight components. While one of the primary reasons for using 
Personal Profile is the heavyweight AWT components, you can create toolkits or 
APIs based on Personal Profile. It also may serve as a basis on which user interface 
libraries, such as those based on the HAVi UI, may be built; it can function as the 
core platform for consumer devices, such as those implementing the DVB 
Multimedia Home Platform (MHP) standard. 


Personal Profile supports static main applications, as well as applets and Xlets. 
The Xlet was developed to provide a streamlined, downloadable application that is 
dynamic and responsive. An Xlet Manager runs Xlets and manages their states 
through a well-defined Xlet lifecycle. 


Personal Profile has been approved by the Java Community Process (JCP), in Java 
Specification Request (JSR) 62. Personal Profile is basically a superset of Personal 
Basis Profile (JSR-129). Applications written to the Personal Basis Profile 
specification should be upward-compatible with Personal Profile. Note that 
Personal Profile has the additional requirements of full web fidelity and legacy 
PersonalJava Application Environment support, which are not included in Personal 
Basis Profile. 


Sun provides a Personal Profile reference implementation based on the 
specification. You can use the Java packages in the reference implementation to 
develop your own applications, applets, Xlets, toolkits, and APIs, or you can create 
your own implementation of Personal Profile. This guide describes the reference 
implementation and the samples included with reference implementation; at the 
same time, it describes Personal Profile in general. However, remember that JSR-62 
is the only official specification for Personal Profile, and you must consult this 
document if you want to create your own Personal Profile implementation that is 
compliant with JSR-62. The reference implementation is only an example of how 
you could implement Personal Profile. 


Personal Profile Programmer’s Guide + September 2002 


Specifications that Personal Profile Can 
Support 


Having been approved through the Java Community Process by electronics 
manufacturers and software vendors, Personal Profile can support many major 
specifications for consumer electronics. Here are some of them: 


Home Audio-Video interoperability (HAVi) — Designed by consumer 
electronics manufacturers, this specification defines APIs and communications 
protocols used to network digital home and entertainment products and provide 
for high-speed, secure data transfer. See www.havi.org for more information. 


DVB Multimedia Home Platform (MHP) — This standard for enhanced 
television and broadcast interactive services defines an interface between 
interactive applications and the devices on which they run: terminals such as 
set-top boxes, digital television sets, and multimedia PCs. It is currently being 
deployed in parts of Europe and Asia. See www.dvb.org and www.mhp. org for 
more information. 


OpenCable Application Profile (OCAP) — This middleware specification for 
interactive television (iTV) services and applications is based on MHP. It 
provides additional features designed for cable television operators. It helps 
developers create iTV applications independent of the cable television system, 
set-top box, and operating system. iTV combines traditional television with the 
interactivity of the Internet, to provide services such as more information about 
shows, instant messaging, shopping, surveys, and playing along with 
gameshows. See www. opencable.com/OCAP.htm1 for more information. 


DTV Applications Software Environment (DASE) — This enhanced television 
standard defines middleware that allows interactive and enhanced applications 
to run on a “common receiver.” These applications should run uniformly on 
different types of hardware platforms and operating systems for receivers. See 
www.atsc.org for more information. 


Many of the iTV specifications that are based on Java can be implemented using 
Personal Profile. The Java TV API is an optional package that can be implemented 
on top of Personal Profile. Currently, however, Sun doesn’t provide a reference 
implementation of the Java TV API that runs on top of the Personal Profile 
reference implementation. 
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Compatibility With Other Specifications 


The APIs in Personal Profile are a superset of those proposed in the Personal Basis 
Profile JSR, so an application or Xlet written for Personal Basis Profile may also be 
run on Personal Profile. Further, the Personal Profile APIs in the java namespace 
are a subset of the APIs in the J2SE Platform, so Personal Profile applications and 
applets which limit themselves to these APIs can also be run in a J2SE 
environment. You could develop your applications in a J2SE application 
environment, for example, being careful to use just the Personal Profile classes and 
packages, and then compile your applications with the Personal Profile class 
library. 


Because Xlets always use the javax.microedition packages, they can’t run in 
the J2SE environment, unless you add the packages they need. 


Personal Profile has the following features, which are the main differences between 
it and the PersonalJava environment: 


m Deprecated methods were removed from Connected Device Configuration 
(CDC) and Foundation Profile — Since Personal Profile runs on top of this 
software, the set of Java packages, classes, and methods is smaller and cleaner. 
See “Running Programs Written for the J2SE Environment” on page 99 for a list 
of deprecated methods that were removed. 


a No “optional” features — If an API has many optional features that you can 
implement, but don’t have to, it can make it harder to write an application that 
runs across all implementations. Personal Profile’s streamlined APIs make it 
easier to write compatible applications, faster to learn, and fit for its purpose, as 
functionality that isn’t necessary wasn’t included. 


For a more in-depth comparison with the PersonalJava environment, see 
Chapter 10, “Comparing Personal Profile and the PersonalJava Environment.” 
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Examples of Possible Implementations 
that Use Personal Profile 


Personal Profile is targeted for a wide range of resource-constrained consumer 
devices, such as PDAs, telematics, iTV, portable stock trading devices, lottery 
terminals, printers, copiers, and medical devices. 


You can use Personal Profile to create a wide variety of applications. Some 
examples are 


m electronic program guides (EPG) for television programs 
m information services applications, such as news tickers and stock tickers 
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a applications synchronized to television content, such as the ability to obtain 
score cards on sports players during a game, or being able to play along with a 
game show 

m home server applications that control many aspects of a home appliance and 
entertainment network, such as heating, lighting, phone, television, movies, 
stereo, security, and so on 

m™ e-commerce applications that use secure transactions 

m applications on hand-held devices that traders can use to buy stock on Wall 
Street 

m educational applications 

= computer games 

m medical monitoring 


Many of these futuristic technologies could make common, everyday tasks — at 
work and at home — easier. For example, if you have a home server, you could 
simplify meal preparation. If you see a recipe you like on a cooking show, you 
could direct the server to print the recipe, order all the groceries you need and have 
them delivered, and preheat the oven at a certain time. 


Product Architecture and Requirements 


The J2ME Platform contains both configurations and profiles. Configurations are 
specifications that detail a virtual machine and a base set of APIs that can be used 
with a certain class of device. A profile builds on a configuration but adds more 
specific APIs to make a complete environment for building applications. Profiles 
usually include APIs for application lifecycle, user interface, and persistent storage. 
Personal Profile is built on a configuration (CDC) and a profile (Foundation 
Profile): 


Personal Profile 


Foundation Profile 


CDC 
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These products provide the following features that are available to applications 
built with Personal Profile: 


a Connected Device Configuration (CDC), JSR-36 — A configuration that provides 
a virtual machine and basic class libraries to support Java language applications 
on consumer electronic and embedded devices such as smart communicators, 
pagers, personal digital assistants (PDAs), and interactive, digital television set- 
top boxes. Typically, these devices run a 32-bit microprocessor/controller and 
have more than 2.0MB of total memory for the storage of the virtual machine 
and libraries. Sun’s implementation of CDC contains the CVM virtual machine. 
CVM is a full-featured virtual machine designed for devices needing the 
functionality of the Java 2 virtual machine feature set, but with a smaller 
footprint. For more information, see http: //java.sun.com/products/cdc/. 


s Foundation Profile, JSR-46 — A profile containing a set of Java APIs which, 
together with CDC, provides a complete J2ME technology application runtime 
environment targeted at consumer electronics and embedded devices. It 
provides a profile of the Java 2 Platform suitable for devices that need support 
for a rich network enabled Java environment, but do not require a GUI. It also 
provides a base profile for other profiles to build on, such as adding GUIs or 
other functionality. For more information, see http: //java.sun.com/ 
products/foundation/. 


Some key features that Personal Profile adds to the stack are 


AWT lightweight and heavyweight components 
BigDecimal and BigInteger support 

limited beans support 

Xlet and applet support 

Inter-Xlet Communication (IXC) 


In addition, devices that implement Personal Profile can optionally include RMI 
OP: 


ms Remote Method Invocation Optional Package (RMI OP) — An API that enables 
you to create distributed Java technology-based to Java technology-based 
applications, in which the methods of remote Java objects can be invoked from 
other Java virtual machines, possibly on different hosts. A Java technology- 
based program can make a call on a remote object once it obtains a reference to 
the remote object, either by looking up the remote object in the bootstrap 
naming service provided by RMI OP or by receiving the reference as an 
argument or a return value. A client can call a remote object in a server, and that 
server can also be a client of other remote objects. RMI OP uses object 
serialization to marshal and unmarshal parameters and does not truncate types, 
supporting true object-oriented polymorphism. For more information, see 
http://java.sun.com/products/jdk/rmi/. 


See the Personal Profile release notes for complete information on Personal Profile 
requirements. 
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Advantages of Personal Profile 


With the deployment of Java in small devices with very specific uses, such as 
television set-top boxes for iTV, telematics boxes for in-vehicle services, and 
handheld devices for targeted applications, it became necessary to have a small 
footprint, graphic-capable implementation of CDC and Foundation Profile, 
including a full AWT graphical toolkit. Personal Profile includes the lightweight 
and heavyweight components of AWT and provides for the addition of graphical 
toolkits designed for specific purposes, such as HAVi Level 2 UI in the television 
market. 


Personal Profile provides the balance of Java compatibility for applications, with 
the need to minimize memory footprint in the device. Application execution 
compatibility is maintained by fully implementing CDC and Foundation Profile. 
Implementation flexibility is achieved by providing support for additional 
graphical toolkits. 


Compared to the following technologies, Personal Profile provides these 
advantages: 


m Foundation Profile and Personal Basis Profile — Personal Profile provides full 
AWT GUI support. 


m PersonalJava environment — Personal Profile provides compatibility with Java 2 
and the J2ME environment. 


a J2SE environment — Personal Profile is a smaller, fit-for-purpose profile, 
designed specifically for consumer electronics devices. 


Three Application Models 


There are three application models you can implement with Personal Profile: 


a An application containing static main(). The application is basically the 
same as a typical application written for the J2SE Platform, except it uses the 
Personal Profile classes only and has a few other restrictions, as described in 
Chapter 3, “Writing Applications.” 


a An applet that is run and managed by the Applet Viewer or a browser. In 
Personal Profile, writing and running an applet is basically the same as you 
would do for JDK 1.1 through the J2SE Platform, version 1.3.1, except you would 
use the Personal Profile classes only. In addition, the applet uses the JDK 1.2 
security model. See Chapter 4, “Writing Applets” for details. 


m One or more Xlets that are run and managed by an Xlet Manager, as described 
here and in Chapter 5, “Writing Xlets.” 
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For the most flexibility, you can write your programs so they can be run as all of 
them: an application, applet, or Xlet, as described in “Writing a Program That Can 
Be Run as an Application, Applet, and Xlet” on page 108. 


For Personal Profile, the Xlet application model has two main pieces: 

m Xlet Manager 

a Xlets 

An Xlet is a Java application (usually downloaded) that implements the Xlet 
lifecycle interface. The Xlet Manager runs Xlets and manages their states: 

a The Xlet Manager can load, initialize, start, pause, and destroy Xlets. 

a An Xlet can pause or destroy itself. 

m An Xlet can ask an Xlet Manager to start it. 

m An Xlet Manager can destroy an Xlet at any time. 

a An Xlet can request that an Xlet Manager not destroy it. 


a An Xlet can move between the active and paused states as many times as 
needed. It is loaded, initialized, and destroyed only once. 


= An Xlet can use Inter-Xlet Communication (IXC) to communicate with other 
Xlets. So an Xlet can use IXC to request that another Xlet change its state, but it 
can’t force a state change in another Xlet. 


Beyond basic lifecycle functions, an Xlet Manager is implementation-specific. It can 
implement other APIs, for example, synchronization APIs with video and audio. 
Xlets should be written so that different Xlet Manager implementations can 
manage them. 


The Personal Profile reference implementation provides a sample Xlet Manager. It 
also provides the Xlet Runner: an Xlet launcher which processes command lines 
and calls methods in the Xlet Manager. You can use the pair as a starting point for 
your own implementations. 
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Comparison of Personal Profile 
Applications, Applets, and Xlets 


The following table compares the Xlet application model with a single Personal 
Profile application and applet. 


Applications (main) 


Xlets 


Applets 


The lifecycle is simply main and 
exit. 


A single application is allowed 
per VM. Some platforms allow 
only one VM at a time. 


An application is typically 
resident on the system that runs 
it. It can be functionally 
equivalent to an Xlet, but has 
fewer security restrictions. It 
doesn’t offer the flexibility of 
being available for dynamic 
download to another system on 
the network. 


Xlets have a well-defined lifecycle 
with Loaded, Paused, Active, and 
Destroyed states. 


Multiple Xlets are allowed per Xlet 
Manager, which is an application 
that uses one VM. The Inter-Xlet 
Communication (IXC) mechanism 
allows Xlets to communicate and 
cooperate with each other. 


An Xlet can be dynamically 
downloaded to the system running 
the Personal Profile 
implementation. This lets users 
execute a provider’s applications 
on-demand; for example, a 
television services provider could 
offer a StockTicker Xlet. However, 
the Xlet is executed under more 
strenuous security restraints than a 
local application as it may have 
originated on an unknown or 
untrusted system. The security 
measures will prevent unknown or 
untrusted Xlets accessing and 
controlling system-critical 
resources. 


The applet lifecycle is controlled 
through init, start, stop, and 
destroy methods. 


Multiple applets are allowed per 
VM. 


Like an Xlet, an applet can be 
dynamically downloaded to the 
system running the Personal 
Profile implementation. It can be 
executed on-demand and under 
rigorous security restraints to 
prevent hostile applets from 
manipulating system-critical 
resources. 


Applets and Xlets are suited to different implementations. Applets were designed 
for use with Internet browsers. Xlets are geared toward consumer device 
applications, such as a television broadcasting environment. They use a well- 
defined lifecycle of Loaded, Paused, Active, and Destroyed states, particularly 
suited to environments like television. 


Applets are significantly wedded to the GUI, but in some cases, a GUI is not 
required for consumer electronics. Applets are typically embedded into an HTML 
document and are bound to AWT, as applet is a subclss of java.awt.Panel. An 
application that does not require any GUI can be suitably run as an Xlet. For 
instance, a Nielson Rating application that runs in the background recording 
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viewer statistics could run with no GUI. Xlets have a newer, more general-purpose 
API with no dependency on AWT or HTML. Many applets, written before Personal 
Profile was introduced, can be run on Personal Profile. 


Applets and Xlets use a similar security model, due to the fact that the Xlet could 
have originated on an unknown or untrusted system and the security restraints 
safeguards the system resources. Xlets should not be able to access system-critical 
resources or interfere maliciously with the operation of other Xlets. 


Comparison of Personal Profile Xlets 
and Other Xlets 


The Xlet model was originally designed for iTV applications. Some existing iTV 
applications use Xlets, such as those based on the Java TV API. They typically 
show some graphics on the screen, synchronize with the video and audio, provide 
some interaction with the user, and have a limited life. 


Having been designed in a generic and portable way, the Xlet model is just as 
appropriate for other types applications running on small footprint devices. As a 
result, Personal Profile included it. 


The Xlet model in the Java TV API (javax.tv.xlet package) and in Personal 
Profile (javax.microedition.xlet package) are almost identical. In general, the 
Java TV API specifies the same Xlet interfaces, lifecycle, and exceptions as Personal 
Profile does. However, the Inter-Xlet Communication (IXC) package in Personal 
Profile, javax.microedition.xlet.ixc, is a new feature that is not a part of 
the Java TV API. See “Implementing Inter-Xlet Communication (IXC)” on page 57 
for more information. 


Development with Reference 
Implementation Packages 


You can use the packages in the Personal Profile reference implementation to 
develop your own applications, applets, Xlets, toolkits, and APIs. Alternatively, 
you can create your own version of Personal Profile based on the specification, 
JSR-62, and develop over it. 


The Personal Profile reference implementation uses GTK+ and restricts 
alphablending behavior and the echo character. Another implementation could 
differ in these respects. 
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If you have a development environment (such as a RAD tool) that helps you 
develop applications for the J2SE Platform, you can use it to develop Personal 
Profile applications. You just need to make sure you use the subset of classes 
available with Personal Profile. When you compile your application against the 
Personal Profile classes, such as the reference implementation classes, it will notify 
you of any classes that aren’t available with Personal Profile (but that might have 
been available with the J2SE Platform). 


See Chapter 9, “Using the Reference Implementation as a Development Platform,” 
for more information on developing with the reference implementation. 


Chapter 1 Introducing Personal Profile 11 


12 Personal Profile Programmer's Guide * September 2002 


CHAPTER 2 


Running the Sample Programs 


This chapter describes how to run the samples provided with the Personal Profile 


reference implementation. It contains the following procedures: 


a “To prepare to run the samples” on page 18 


a “To run the HelloWorld sample” on page 18 


a “To run the DemoApplet sample” on page 18 


a “To run the SimpleXletDemo sample” on page 19 


a “To run the Inter-Xlet Communication (IXC) sample” on page 20 


a “To run the ColorBean sample” on page 20 


a “To run the FrameDemo sample” on page 21 


a “To run a group of PPDemo samples as an application” on page 22 


a “To run a group of PPDemo samples as an applet” on page 23 


a “To runa group of PPDemo samples as an Xlet” on page 23 


a “To run the PPDemo samples individually” on page 24 


The sample code is described in several chapters of this guide. 


The Personal Profile samples are listed in the following table. 


Sample Description Running the Sample! 

HelloWorld A simple application that displays Hello “To run the HelloWorld 
World. sample” 

DemoApplet A simple applet that displays messages “To run the DemoApplet 
about the applet lifecycle. sample 

SimpleXletDemo A simple Xlet that displays an image. “To run the 

SimpleXletDemo sample” 

Inter-Xlet Two Xlets that mimic a flight simulator, “To run the Inter-Xlet 

Communication where a server maintains the position of | Communication (IXC) 

(IXC) an airplane, and a client receives sample” 


position updates. The Xlets use IXC to 
communicate. 
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Sample Description Running the Sample! 

ColorBean A simple bean that displays a colored “To run the ColorBean 
rectangle in a container. It has a sample” 
beanColor property and includes 
PropertyChangeSupport. The 
rectangle changes colors. 

ColorBeanTester is a registered listener 
of ColorBean and is notified when 
beanColor changes. 

FrameDemo An application that illustrates Frame “To run the FrameDemo 
behavior when you click a button. The sample” 
buttons are a custom lightweight 
component, as opposed to the standard 
heavyweight AWT components. 

PPDemo A class used by the PPDemoFrame, “To run a group of PPDemo 
PPDemoApplet, and PPDemoXlet samples as an application” 
classes to display a group of samplesas “To runa group of PPDemo 
an application, applet, or Xlet, or samples as an applet” 
display one sample at a time as an “To run a group of PPDemo 
application. samples as an Xlet” 

“To run the PPDemo 
samples individually” 

Color A sample that creates five arrays of “To run a group of PPDemo 
colors and displays those colors. From samples as an application” 
top to bottom, the sample shows: “To run a group of PPDemo 
e A range of RGB color values. samples as an applet” 
¢ Grayscale color values. “To run a group of PPDemo 
e Standard color values. samples as an Xlet” 
¢ The effect of the darker and lighter “To run the PPDemo 
methods of the Color class. samples individually” 
¢ Alphablending with colors. Note that 
the Personal Profile reference 
implementation doesn’t support 
alphablending, but another 
implementation might. 

SystemColor A sample that displays the standard “To run a group of PPDemo 


system colors contained in the 
SystemColor class. It creates an array of 
all the public static final SystemColor 
fields. It also creates an array of strings 
containing the RGB values of the 
corresponding colors and their names. 


samples as an application” 
“To run a group of PPDemo 
samples as an applet” 

“To run a group of PPDemo 
samples as an Xlet” 

“To run the PPDemo 
samples individually” 
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Sample Description Running the Sample! 

Draw A sample that uses the draw and fill “Toruna group of PPDemo 
methods in the Graphics class. The samples as an application” 
shapes — lines, rectangles, ovals, and “To run a group of PPDemo 
polygons — are drawn to fit inside each samples as an applet” 
other to save space and are in different “To runa group of PPDemo 
colors to make the shapes visible. samples as an Xlet” 

“To run the PPDemo 
samples individually” 

Image A sample that demonstrates image “To run a group of PPDemo 
capabilities. First, it loads images using samples as an application” 
the get Image method in Toolkit. It “To run a group of PPDemo 
creates three rows of images: samples as an applet” 
¢ The first row of images show that “To run a group of PPDemo 
various image formats can be handled, — samples as an Xlet” 
by displaying GIF, JPG, and PNG “To run the PPDemo 
images with a range of color and samples individually” 
grayscale values. 
¢ The middle row shows a transparent 
GIF image in three ways: calls the 
drawImage method, calls the 
drawImage method with a red 
background, and uses a buffered image 
with drawImage. 
¢ The third row shows alphablending 
capabilities by drawing the image after 
setting the alpha composite values to 
0.0, 0.2, 0.4, 0.6, 0.8, and 1.0 using the 
setComposite method of Graphics2D. 

Note that the Personal Profile reference 
implementation doesn’t support 
alphablending, but another 
implementation might. 

You can also drag the mouse across the 
display and it draws a Duke in XOR 
mode. 

Animator A sample that displays an animated “To run the PPDemo 
GIF. samples individually” 

Font A sample that shows the standard fonts “To runa group of PPDemo 


— serif, sans serif, monospaced, Dialog, 
DialogInput, and Symbol — using the 
PLAIN, BOLD, ITALIC, and 
BOLD+ITALIC styles. 


samples as an application” 
“To run a group of PPDemo 
samples as an applet” 

“To run a group of PPDemo 
samples as an Xlet” 

“To run the PPDemo 
samples individually” 
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Sample Description Running the Sample! 
FontMetrics A sample that displays the letter g at “To run a group of PPDemo 
the junction of two lines, which samples as an application” 
represent the left-hand side and the “To run a group of PPDemo 
base-line of the letter. It then displays samples as an applet” 
the font size and the values returned by “To runa group of PPDemo 
the FontMetrics methods, such as samples as an Xlet” 
getAscent, getDescent, and so on. “To run the PPDemo 
samples individually” 
Mouse A sample that shows the x and y “To run a group of PPDemo 
coordinates of the mouse cursor inside a samples as an application” 
mouse as it is moved or dragged across “To runa group of PPDemo 
the component. It also alters the outline samples as an applet” 
of the sample when the mouse cursor “To run a group of PPDemo 
enters or exits, and shows which mouse _ samples as an Xlet” 
buttons are pressed or released. “To run the PPDemo 
samples individually” 
Cursor A sample that displays the available “To run a group of PPDemo 
mouse cursor shapes. The paint samples as an application” 
method draws six rectangles to display “To runa group of PPDemo 
the Default, Cross hair, Hand, Move, samples as an applet” 
Text, and Wait cursors, and a border “To run a group of PPDemo 
with corners to display the different samples as an Xlet” 
Resize cursors. By moving the mouse “To run the PPDemo 
over the rectangles or borders, it will samples individually” 
automatically change the cursor to the 
appropriate shape. 
Keyboard A sample that shows the values “To run a group of PPDemo 


returned by KeyEvents when keyboard 
keys are pressed. It draws a keyboard 
and whenever a key is pressed, the 
getKeyChar, getKeyCode, and 
getModifiers methods are called and 
their values are displayed. 


samples as an application” 
“To run a group of PPDemo 
samples as an applet” 

“To run a group of PPDemo 
samples as an Xlet” 

“To run the PPDemo 
samples individually” 
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Sample 


Description 


Running the Sample! 


Layout, 
FlowLayout, 
BorderLayout, 
GridLayout, 
GridBagLayout, 
CardLayout, 
NullLayout 


Widget 


The Layout sample is a combination of 
the FlowLayout, BorderLayout, 
GridLayout, GridBagLayout, 
CardLayout, and NullLayout samples. 
¢ FlowLayout creates seven buttons of 
different widths to show that the 
FlowLayout manager will respect the 
preferred sizes of its components. 

¢ BorderLayout creates five buttons 
and puts them in the North, South, East, 
West, and Center positions, where they 
are resized to fit. 

¢ GridLayout uses three rows and two 
columns and buttons are stretched to fill 
the grid. 

¢ GridBagLayout can put buttons 
anywhere, as shown by the fact that 
button “four” is placed before button 
“threethreethree,” even though it was 
added later. 

¢ CardLayout shows how buttons can 
be displayed across the entire width of 
the container one at a time. Click the 
button to display the next card. 

¢ NullLayout places buttons at absolute 
positions, but they can overlap. 


The buttons are a custom lightweight 
component, as opposed to the standard 
heavyweight AWT components. 


The Widget sample demonstrates some 
common Personal Profile AWT 
components, including 
TextArea 

TextField 

Button 

Checkbox 

Choice 

List 

PopupMenu 

Menultem 

MenuShortcut 

Panel 


“To run a group of PPDemo 
samples as an application” 
“To run a group of PPDemo 
samples as an applet” 

“To run a group of PPDemo 
samples as an Xlet” 

“To run the PPDemo 
samples individually” 


“To run a group of PPDemo 
samples as an application” 
“To run a group of PPDemo 
samples as an applet” 

“To run a group of PPDemo 
samples as an Xlet” 

“To run the PPDemo 
samples individually” 


1. The command lines assume that the current working directory is personal/build/linux-i686/ 


democlasses. 
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v To prepare to run the samples 


When you install the Personal Profile reference implementation, as described in the 
release notes, you simultaneously compile the samples. The compiled classes are 
located in personal/build/linux-i686/democlasses of the reference 
implementation. The source files are in personal /src/share/personal/demo. 


You might need to recompile the samples if you change the source files, or you 
remove the compiled files. To compile the samples, you could enter the following 
command lines from the directory where you placed the Personal Profile reference 
implementation files: 


cd personal/build/linux-i686 


make J2ME_CLASSLIB=personal CVM_GNU_TOOLS_PATH=/usr/bin\ 
JDK_HOME=your-java-—home-dir democlasses 


Before entering this make command, you must have already built the reference 
implementation. 


After the samples are compiled, you can run them, as described in the following 
sections. In these sections, the command lines assume that the current working 
directory is personal/build/linux-i686/democlasses. 


Vv To run the HelloWorld sample 


Enter this command line: 


../bin/cvm HelloWorld 


The following window appears: 


<unknown> je) 3) 


Hello World 


See “A Simple Application” on page 27 for details. 


v To run the DemoApplet sample 


Enter this command line: 


../bin/cvm sun.applet.AppletViewer LifeCycleApplet.html 
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The following window appears: 


=| Applet Viewer: LifeCycleApplet.class Ja 
Applet 


initializing — starting 


VApplet started, 


See “The Basic Parts of an Applet” on page 34 for details. 


To run the SimpleXletDemo sample 


Enter this command line: 


../bin/cvm com.sun.xlet.XletRunner -name SimpleXletDemo -path . 


The following window appears: 


| Xlet Frame al 
XlofRunner  SimpheXletDemo 


See “The Basic Parts of an Xlet” on page 41 for details. 
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v To run the Inter-Xlet Communication (IXC) sample 


Enter this command line: 


../bin/cvm IXCDemo.IXCMain 


The following text appears: 


Manager: client created 
client: constructed 
Manager: server created 
PlaneClient starting... 
PlaneClient looking for import registry. 

PlaneClient waiting for the server for 2 second 

server: constructed 

PlaneServer was started. 

PlaneClient looking for plane. 

PlaneClient adding self as listener. 

PlaneImp] gets new listener IXCDemo.ixcXlets.clientXlet.PlaneClient@f4264f 
Other plane: IxXcDemo. eee eee serverXlet.Planelmp]<speed=0.0, heading=0.0, pos 
ition=Position(x=0.0, y=0.0)> 

Other equals primary? true 

PlaneClient setting speed ae sreanine 

PlaneServer accelerates by 

PlaneServer turns by 1. oabagresi1acsa7e 

Other equals primary? false 


See “Implementing Inter-Xlet Communication (IXC)” on page 57 for details. 


Note that when using the XletRunner with IXC, the Xlet should not be found in the 
classpath and the Xlet path is relative to the current directory. The IXC sample is 
structured so this is not an issue. 


You might need to press Control+C to exit the sample. 


The rest of the samples are described in Chapter 8, “Implementing Common 
Programmatic Features.” 


v To run the ColorBean sample 


Enter this command line: 


../bin/cvm ColorBeanTesterDemo 
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The following window appears: 


= <unknown> lal] 


See “Working with JavaBeans” on page 173 for details. 


To run the FrameDemo sample 


Enter this command line: 


../bin/cvm FrameDemo 


The following window appears: 


Click a button to see Frame behavior: 


m New — A new Frame appears. 

a Title — An asterisk (*) is added to the title in the titlebar. 

m Size — The size of the window changes. This behavior happens only when the 
window is resizable (described next). 

m Resizable — Click the button to toggle the ability of the Frame to be resized. The 
button turns red when you can’t resize the Frame. You can test the change with 
the Size button. 

a Location — Change the location of the Frame on the screen. 

m State — Minimize (iconify) the window. 


See “Working with Frames” on page 120 for details. 


You can run many of the other samples described in Chapter 8 together. 
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Vv To run a group of PPDemo samples as an application 


Enter this command line to see the displays all at once: 


../bin/cvm PPDemoFrame 


A window similar to the following appears: 


Enter this command line to see the displays one at a time by clicking a button: 
../bin/cvm PPDemoFrame -all 


The following window appears: 


Demos Check Boxas Dialogs Ext 


<= Right click here for Popup Menu 
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To run a group of PPDemo samples as an applet 


Enter this command line to see the displays one at a time by clicking a button: 


../bin/cvm sun.applet.AppletViewer PPDemoApplet.html 


The following window appears: 


iS Applet viewer: PPDemoApplet.class Ela) 


is 
i 


pplet started 


See “Writing a Program That Can Be Run as an Application, Applet, and Xlet” on 
page 108 for information on creating a program that can be run as an application, 
applet, or Xlet. 


To run a group of PPDemo samples as an Xlet 


Enter this command line to see the displays one at a time by clicking a button: 


../bin/cvm com.sun.xlet.XletRunner -name PPDemoXlet -path . 


The following window appears: 


| Xlet Frame je}a) 
XwtRunner PPDemoXtet 


Draw 

Image _ | 

Font 
FontMetrics | 


7 
rh 


See “Writing a Program That Can Be Run as an Application, Applet, and Xlet” on 
page 108 for information on creating a program that can be run as an application, 
applet, or Xlet. 
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v To run the PPDemo samples individually 


Enter this command line: 


../bin/cvm PPDemoFrame demo 


Where demo can be any of the following: 
a Color — See “Working with Color” on page 131 for details. 
a SystemColor — See “Working with Color” on page 131 for details. 


a Draw — See “Displaying Graphics, Images, and Animations” on page 139 for 
details. 


a Image — See “Displaying Graphics, Images, and Animations” on page 139 for 
details. 


a Animator — See “Displaying Graphics, Images, and Animations” on page 139 
for details. 


a Font — See “Working with Fonts” on page 150 for details. 

m FontMetrics — See “Working with Fonts” on page 150 for details. 

ms Mouse — See “Working with Cursors” on page 154 for details. 

m Cursor — See “Working with Cursors” on page 154 for details. 

mu Keyboard — See “Publishing and Subscribing to Events” on page 162 for details. 
a Layout — See “Working with Layouts” on page 167 for details. 

a FlowLayout — See “Working with Layouts” on page 167 for details. 

a BorderLayout — See “Working with Layouts” on page 167 for details. 
a GridLayout — See “Working with Layouts” on page 167 for details. 

a GridBagLayout — See “Working with Layouts” on page 167 for details. 
a CardLayout — See “Working with Layouts” on page 167 for details. 

a NullLayout — See “Working with Layouts” on page 167 for details. 


a Widget — See “Working with AWT Components” on page 123 for details. Note 
that the command line ../bin/cvm PPDemoFrame doesn’t display the Widget 
sample. 


For example, if you run Layout, the following window appears: 


| | threethreethres 


The command line optionally takes arguments. If you don’t specify arguments, the 
sample is run with a default width, height, and font size, if applicable. The defaults 
are different for each sample. 
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To specify a width and height: 


../bin/cvm PPDemoFrame demo width height 
For the Font and FontMetrics samples, you can specify a font size. 


To specify a font size: 


../bin/cvm PPDemoFrame demo font-size 


To specify a width, height, and font size: 


..-/bin/cvm PPDemoFrame demo width height font-size 
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CHAPTER 3 


Writing Applications 


Writing applications for Personal Profile is very similar to writing applications 
using common Java programming techniques, except you use the streamlined APIs 
provided with Personal Profile, instead of the complete set of APIs provided in the 
J2SE environment. 


The chapter contains the following sections: 

a “A Simple Application” on page 27 

a “Implementation Considerations” on page 28 

For more information on specific programming tasks related to writing 
applications, see Chapter 8, “Implementing Common Programmatic Features.” To 
start developing applications quickly, you can develop over the Personal Profile 


reference implementation, as described in Chapter 9, “Using the Reference 
Implementation as a Development Platform.” 


A Simple Application 


In personal/src/share/personal/demo of the Personal Profile reference 
implementation is the source for a simple Hello World application. Following is the 
sample code. Notice that the code is similar to how you would write an application 
using common Java programming techniques. 


import java.awt.*; 
import java.awt.event.*; 


// Create a Frame and make it visible. 
public class HelloWorld extends Frame { 
public static void main(String[] args) throws Exception { 
final Frame frame = new HelloWorld(); 
frame.setSize(640, 400); 
frame.addWindowListener (new WindowAdapter() { 
public void windowClosing(WindowEvent we) { 
frame.dispose(); 
System.exit (0); 


27 


} 
i 
frame.setVisible (true) ; 


} 


// Display the words "Hello World" in red Dialog font. 
public void paint (Graphics g) { 
g.setFont (new Font ("Dialog", Font.PLAIN, 50)); 
g.setColor (Color.red) ; 
g.drawString("Hello World", 150, 200); 


} 


When you run the application, as described in Chapter 2, “Running the Sample 
Programs,” the following window appears: 


sunknown> J2)3) 


Hello World 


Another example of an application is the Xlet Manager, described in Chapter 6, 
“Writing Xlet Managers.” 


Implementation Considerations 


Personal Profile can help you write new, exciting types of applications, such as 
product-picking applications for handheld wireless devices; small peer-to-peer 
messaging clients; touch-screen telephone applications; peer-to-peer object 
swapping applications; and objects using genetic-like properties in a collaborative 
environment that evolves as their users do (for example, a sharable mail filter 
object). Personal Profile was modeled after familiar environments so you can get 
started quickly. This section describes some differences between Personal Profile 
and these environments that you should be aware of when you write applications. 
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Writing applications for Personal Profile is very similar to writing applications for 
the J2SE environment. Overall, Personal Profile applications should be able to run 
in a J2SE environment. However, there are some incompatibilities. Personal Profile 
uses a subset of the APIs provided with the J2SE environment. Some examples are 


m java.beans contains a subset of the J2SE package. 


Personal Profile contains only the run-time classes, and none of the design-time 
classes. 


m Some deprecated methods were removed. 


The J2SE environment contains a number of deprecated methods, which have 
been removed from Personal Profile, for example, peer-related methods. An 
application that relies on these deprecated methods will need to be modified. 
See “Running Programs Written for the J2SE Environment” on page 99 for more 
information. However, some deprecated methods remain, making Personal 
Profile largely backward-compatible with the PersonalJava environment. 


Personal Profile provides javax.microedition packages that aren’t present in 
the J2SE environment. If you want your application to run in the J2SE environment, 
do not use these packages, or provide the packages with your application. The 
microedition packages are for Xlets, so unless you’re writing an Xlet Manager 
application, you can exclude these packages. 


Personal Profile has some optional restrictions in the following areas, as described 
in the specification: 


java.awt.Component 
java.awt.Dialog 

java.awt.Frame 
java.awt.Graphics2D 
java.awt.AlphaComposite 
java.awt.TextField.setEchoChar 


The reference implementation restricts the last two. 


Because Personal Profile applications are designed to run on small devices, the 
behavior for Frames and Dialogs can be made more restrictive than that for the 
J2SE environment. 


An implementation of Personal Profile can restrict Frame behavior as follows. 


ms An implementation may support one Frame size only. If the Frame size is 
restricted, when an application attempts to change the size of any Frame (such 
as by using the following methods), the call fails silently: 


setSize(int, int) 

setSize (Dimension) 
setBounds(int, int, int, int) 
setBounds (Rectangle) 


When the Frame is made visible, its size will be changed to reflect the size 
supported by the implementation. If the supported size is different than the 
requested size, a resize event will be generated. 
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a An implementation may prohibit a user from resizing Frames. In this case, 
attempts to make any Frame resizable will fail silently: 


setResizable (boolean) 


ms An implementation may support one Frame location only. In this case, attempts 
to change the location of any Frame will fail silently: 


setLocation(int, int) 
setLocation (Point) 
setBounds(int, int, int, int) 
setBounds (Rectangle) 


ms An implementation may prohibit iconification. In this case, attempts to iconify 
any Frame will fail silently: 


setState (int) 


ms An implementation may not support a visible title on Frames. In this case, the 
methods setTitle (java.lang.String) and getTitle() onall Frames 
behave as normal, but no title is visible to the user: 


Frame (String) 
Frame (String, GraphicsConfiguration) 
setTitle (java.lang.String) 


The sample application, FrameDemo, illustrates how to work with Frames in 
Personal Profile. See “Working with Frames” on page 120 for more information. 


Dialogs can have some of the same limitation as Frames, except for iconification. 


Many of the limitations are implementation-specific. Limitations of a specific 
implementation require that a system property be set. The property should only be 
set if there is a limitation. The system properties can be retrieved through the 
System.getProperties method. Some properties specify degrees of support, 
rather than absolutes, including MouseEvent and KeyEvent. Here is a list of some 
properties: 


AlphaComposite.SRC_OVER.isRestricted 
Component.setCursor.isRestricted 
Frame.setSize.isRestricted 
Frame.setResizable.isRestricted 
Frame.setLocation.isRestricted 
Frame.setState.isRestricted 
Frame.setTitle.isRestricted 
event .MouseEvent.isRestricted 
event .MouseEvent.supportLevel 
event .KeyEvent.isRestricted 
event .KeyEvent.supportMask 


The first property involves alphablending. Not all platforms support full 
alphablending, and Personal Profile doesn’t require that all implementations 
support full alphablending. So when you use alphablending, the results can vary 
on different platforms. 
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When developing an application for AWT, the display size is an important 
consideration and is not similar to developing for the J2SE Platform, because the 
desktop has a much richer environment. You should thoroughly research the 
intended audience and platform, including the display size of the target devices 
and the input mechanism, before starting any interface development work. To 
create a successful application using AWT, you need to study how the intended 
application will function in the real world, and how to make it as simple and 
intuitive as possible for end users. A good reference for AWT programming is 


http://developer. java.sun.com/developer/onlineTraining/awt 
In addition, the following document describes effective layout management: 


http://developer. java.sun.com/developer/onlineTraining/GUI/ 
AWTLayoutMgr/index.html 


Chapter 3 Writing Applications 


31 


32 Personal Profile Programmer’s Guide * September 2002 


CHAPTER 4 


Writing Applets 


An applet is a program written in the Java programming language that can be 
included in an HTML page, much in the same way an image is included. When 
you use a Java technology-enabled browser to view a page that contains an applet, 
the applet's code is transferred to your system and executed by the browser's Java 
Virtual Machine (JVM). 


Personal Profile has applet support, which is the primary method of executing Java 
programs over the web. In Personal Profile, writing and running an applet is 
basically the same as you would do for JDK 1.1 through J2SE Platform, version 
1.3.1, except you would use the Personal Profile classes only. In addition, the applet 
uses the JDK 1.2 security model. Properly written applets should be compatible 
with Personal Profile. 


For more information on applets in general, see 
http://java.sun.com/applets/index.html 

This chapter tells you how to write an applet for Personal Profile. It contains the 
following sections: 

a “The Basic Parts of an Applet” on page 34 

a “Implementation Considerations” on page 39 

For more information on specific programming tasks related to writing applets, see 
Chapter 8, “Implementing Common Programmatic Features.” To start developing 
applets quickly, you can develop over the Personal Profile reference 


implementation, as described in Chapter 9, “Using the Reference Implementation 
as a Development Platform.” 
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The Basic Parts of an Applet 


When you write an applet using Personal Profile, it can perform the following 
fundamental functions: 


1. Import the needed Personal Profile classes. 
You always need to import the Applet class. 


. Implement the method to initialize the applet: init. 
. Implement the method to start the applet: start. 


. Implement the method to stop the applet: stop. 


a FF Ww N 


. Implement the method to destroy the applet: dest roy. 


Because an applet extends the Applet class, it’s not necessary to actually 
implement any of the lifecycle methods. However, most applets do override one or 
more of these methods to perform their functions. The Applet Viewer or a browser 
calls the lifecycle methods. 


DemoApplet Sample 


In personal/src/share/personal/demo of the Personal Profile reference 
implementation is the source for a simple applet that illustrates these basic 
functions, and displays information in a window. Following is the sample code, 
which is described in the rest of this section. Notice that the code is almost the 
same as that in the Java tutorial: 


http://java.sun.com/docs/books/tutorial/applet/overview/ 
lifeCycle.html 


You can run the sample using the default Applet Viewer provided with the 
reference implementation. 


import java.applet.Applet; 
import java.awt.Graphics; 
import java.awt.Color; 


public class LifeCycleApplet extends Applet { 


StringBuffer buffer; 
public void init () { 


buffer = new StringBuffer (); 
addItem("Initializing ... "); 
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public void start () { 
addiItem("starting ... "); 


public void stop() { 
addItem("stopping ... "); 


public void destroy () { 
addiItem("preparing for unloading... "); 


void addItem(String newWord) { 
System.out.printin (newWord) ; 
buffer.append (newWord) ; 
repaint (); 


public void paint (Graphics g) { 
g.setColor (Color.red) ; 
//Draw the current string. 
g.drawString(buffer.toString(), 5, 25); 


The following basic HTML page contains the <APPLET> tag for running the applet 
in the Applet Viewer: 


<html> 

<body> 

<applet code="LifeCycleApplet.class" width=500 height=275> 
</applet> 

</body> 

</html> 


An applet is always run from an HTML page through the <APPLET> tag. For more 
information on the <APPLET> tag, see 


http://java.sun.com/products/jdk/1.1/docs/guide/misc/ 
applet .html 
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When you run the applet, as described in Chapter 2, “Running the Sample 
Programs,” the following window appears: 


Applet Viewer: LifeCycleApplet.class ea 


Applet 


initializing starting 


\Applet started 


The applet displays lifecycle messages in its window. In addition, when you run 
the applet in the Applet Viewer, the output also appears on the console. You can 
use the Applet menu to select lifecycle operations. For example, if you choose Stop, 
the applet is stopped; when you choose Restart, the applet is stopped, destroyed, 
initialized, and then started again. If you iconify the window, the applet is stopped; 
when you deiconify it, the applet is started. 


When you run an applet in a browser, how lifecycle operations are performed is 
dependent on the browser. 


The following sections describe this applet. 


Importing the Required Applet Classes 


The sample Personal Profile applet relies on the following classes: 


import java.applet.Applet; 
import java.awt.Graphics; 
import java.awt.Color; 
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The inheritance hierarchy for the Applet class is. 


java.lang. 
Opies 


java.awt. 
omponent 


java.awt. 
ontainer 


java.awt. 
Panel 


java.applet. 
App et 


From the Component class, applets inherit drawing methods, for representing the 
applet on the screen, and event-handling methods, for processing user input and 
other changes. From the Container class, applets inherit the ability to hold AWT 
Components and use layout managers to position the Components. The Applet 
class extends Panel, so the applet has a container from the beginning and doesn’t 
need to obtain one. (In contrast, an Xlet needs to call get Container.) 


Most applets have a GUI because they appear in a browser window. Because the 
Applet class is a subclass of the Panel class, creating an applet's GUI is similar to 
creating an application’s GUI. However, the applet's window (the browser 
window) already exists. Applets inherit the default layout manager of Panel: 
FlowLayout. They also inherit its AWT event and drawing model. 


The sample applet imports the Graphics class as it is needed in the paint method. 
Notice that the paint method takes a Graphics g as an argument and the setColor 
method takes a Color object: 


public void paint (Graphics g) { 
g.setColor(Color.red) ; 
//Draw the current string. 
g.drawString(buffer.toString(), 5, 25); 
} 


Note that the StringBuffer class is not imported explicitly, as it is in the Java 
tutorial. This is because the class is already loaded during the startup of CVM and 
the Applet Viewer. 
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Writing a Constructor and Extending the Applet 
Class 


As mentioned earlier, all applets must extend the Applet class: 


public class DemoApplet extends Applet { 


The Applet Viewer or browser calls the constructor to create the applet. The 
Applet class allows an Applet Viewer or browser to control the applet lifecycle, 
including initializing, starting, stopping, and destroying an applet. Each applet can 
implement the following Applet methods for the Applet Viewer or browser to call: 


m init — Initializes the applet. It is called only once. 


m start — Starts the applet. You must implement this method if you want the 
applet to do something. 


m stop — Stops the applet. 
m destroy — Performs final cleanup on the applet. It is called only once. 


The applet can contain code in the method bodies that performs the necessary 
processing at that stage of the lifecycle. For example, it might have code that opens 
a network connection, reads user input, paints an image on the screen, releases 
resources, and so on. If an applet is made of multiple classes, it is through the class 
that extends the Applet class that the Applet Viewer or browser accomplishes 
lifecycle changes. 


Initializing the Applet and Obtaining the 
AppletContext 


After the Applet Viewer or browser creates an applet, it initializes it with an init 
call. During applet initialization, you might perform operations such as opening a 
network connection or thread, populating properties with values, and other tasks 
that are best done at this time. This method is called only once during the lifecycle 
of an applet. If the call returns successfully, the applet is initialized. 


The applet automatically gets an AppletContext when it is loaded. The 
AppletContext corresponds to an applet's environment: the document containing 
the applet and the other applets in the same document. The applet context is 
responsible for fetching images and audio files, and so on. 


Starting the Applet 


After initialization, the applet can be started. Within the start method, the applet 
performs the functions it was designed for. If the applet has a GUI, the work done 
in the method body is usually small, such as painting the user interface on the 
screen or re-initiating some activity. A non-graphical applet would simply start 
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whatever processing it does. For example, if an applet performed some sort of 
batch job and the batch processing took some time, it could begin its work and 
return from the start method. 


Every applet that does something after initialization must override the start 
method. One exception would be responses to user actions. Typically, though, the 
start method either performs the applet's functions or starts up one or more 
threads to perform the functions. 


After the start call successfully returns, the sample displays text in the window. 
(The window appeared during initialization.) 


Stopping the Applet 


After starting an applet, it can be stopped, after which it can be started again, as 
many times as needed. To stop an applet that has been started, the Applet Viewer 
or browser calls stop. If the call successfully returns, the applet is stopped. For the 
Applet Viewer included with the reference implementation, the Applet Viewer calls 
stop when the applet is iconified or you choose Applet | Stop. It also makes the 
applet invisible. Since the Applet Viewer or browser is still running, the window 
remains. 


Destroying the Applet 


The Applet Viewer or browser can destroy an applet at any time by calling the 
destroy method. If the call successfully returns, the applet is destroyed, and this 
instance will not be run again. To destroy the sample, close the window. 


To clean up, an applet might remove any applet display from the screen, close I/O 
and network connections, and perhaps save the state to persistent storage, if this is 
supported. (The sample applet doesn’t perform this cleanup.) 


Implementation Considerations 


Writing an applet for Personal Profile is very similar to writing an applet for the 
JDK 1.1 through the J2SE Platform, version 1.3.1. However, you need to use the 
subset of APIs provided with Personal Profile. That said, many applets written for 
the J2SE environment do run with Personal Profile without modification. 


In Personal Profile, some methods provided with the J2SE environment have been 
deprecated, and some removed. For example, Thread. stop was deprecated and 
any “old” applet that uses these methods will not run properly with the reference 
implementation. For more information on deprecated and removed methods, see 
“Running Programs Written for the J2SE Environment” on page 99. 
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Applets written for Personal Profile use the JDK 1.2 security model. For more 
information on the security model, see 


http://java.sun.com/security/signExamplel12/ 


Note that the Applet Viewer provided with Personal Profile is basically the same as 
that provided with the J2SE environment. 
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CHAPTER 5 


Writing Xlets 


This chapter provides the basic information you need to write Personal Profile 
Xlets that conform with the application model described in the previous chapter. It 
describes the simple Xlet sample included with Personal Profile. 


The chapter contains the following sections: 

a “The Basic Parts of an Xlet” on page 41 

a “Xlet Lifecycle and States” on page 49 

a “Implementing Inter-Xlet Communication (IXC)” on page 57 

For more information on specific programming tasks related to writing Xlets, see 
Chapter 8, “Implementing Common Programmatic Features.” To start developing 
Xlets quickly, you can develop over the Personal Profile reference implementation, 


as described in Chapter 9, “Using the Reference Implementation as a Development 
Platform.” 


The Basic Parts of an Xlet 


An Xlet is a Java application (usually downloaded) that implements the Xlet 
lifecycle. A Personal Profile Xlet must perform the following fundamental 
functions: 


. Import the needed Personal Profile classes. 


. Implement the method to initialize the Xlet: initXlet. 


It receives an XletContext from the Xlet Manager. 


. For graphical Xlets, get the parent container to put AWT components in. 


Typically, the Xlet gets the container while initializing the Xlet, but it could also get 
it at other times, such as while starting the Xlet. It often makes sense to get the 
container during initialization, because then you only get it once during the 
lifecycle. 
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4. Implement the method to start the Xlet: start Xlet. 


5. Implement methods that pause and destroy the Xlet: pauseXlet and 


destroyXlet. 


You can destroy an Xlet by choosing Destroy from the window menu or by closing 
the window. Similarly, you can pause an Xlet by choosing the Pause menu item or 
by iconifying the window; you can activate it again by choosing the Activate menu 
item or bydeiconifying the window. 


SimpleXletDemo Sample 


In personal/src/share/personal/demo of the Personal Profile reference 
implementation is the source for a simple Xlet that illustrates these basic functions, 
and displays an image in a window. (For the reference implementation, it’s a GIK 
window.) Following is the sample code, which is described in the rest of this 
section. Notice that the code is similar to how you would write an applet using 
common Java programming techniques. You can run it using the default Xlet 
Manager provided with the reference implementation, described toward the end of 
this chapter. 


// Import the necessary classes. 
// The following package is provided by Personal Profile. 


// It contains the Xlet and XletContext interfaces. 
import javax.microedition.xlet.*; 


// The Xlet will use the BorderLayout layout manager. 
import java.awt.BorderLayout; 


// An Xlet is a component. 
import java.awt.Component; 


// The Xlet is displayed from within a container, which is within a 
// Frame that the Xlet Manager created. 


import java.awt.Container; 

//Import packages needed to display the image. 
import java.awt.Color; 

import java.awt.Dimension; 

import java.awt.Graphics; 

import java.awt.Image; 

import java.awt.MediaTracker; 

import java.net.URL; 


// Create the SimpleXletDemo class. An Xlet is a component that 
// implements the Xlet interface. When the object is initially 
// constructed, the Xlet is in the Loaded state. 

public class SimpleXletDemo extends Component implements Xlet { 


// Create Container and Image objects. The Image object will be 
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// displayed within the Container object. 
private Container rootContainer; 
private Image image; 


// Initialize the Xlet. The Xlet stores the context for 
// future use. When the call successfully completes, the Xlet is 
// in the Paused state. 
public void initXlet (XletContext context) { 
log("initXlet called"); 


// Load and then paint the image. 
// This is similar to standard JDK programming, 
// except you need to get the container first. 
// XletContext.getContainer gets the parent container for the 
// Xlet to put its AWT components in. The size and location is 
// arbitrary, so needs to be set. Later, calling 
// setVisible(true) makes the container visible. 
try { 
rootContainer = context.getContainer(); 
rootContainer.setSize (400,300); 
rootContainer.setLayout (new BorderLayout () ); 
rootContainer.setLocation(0,0); 
rootContainer.add("North",this) ; 
rootContainer.validate (); 
image = loadImage ("images/duke.gif"); 
} catch (Exception e) { 
e.printStackTrace(); 


} 
// Start the Xlet. When the call successfully completes, the Xlet 
// is in the Active state. 
public void startXlet() { 
log("startXlet called"); 


// Make the container visible. This method calls 
// the paint method. 
rootContainer.setVisible (true); 


// When this call successfully completes, the Xlet is in the 
// Paused state. The Xlet Manager can make it Active again, 
// as needed. 
public void pauseXlet() { 

log("pauseXlet called"); 


// Make the container invisible. If the Xlet Manager starts 
// the Xlet again, the container will be made visible. 
rootContainer.setVisible (false) ; 


// When this call successfully completes, the Xlet is in the 
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// Destroyed state, and can’t become Active or Paused again. 
public void destroyXlet (boolean unconditional) { 
log("destroyXlet called"); 


// Cleanup for the Xlet. Destroy the container and the image. 
rootContainer.remove (this); 
image = null; 


void log(String s) { 
System.out.printin("SimpleXlet: " + s); 


public void paint(Graphics g) { 
int w = getSize().width; 
int h = getSize().-height; 
g.setColor(Color.blue) ; 
g.fi1113DRect (0,0,w-1, h-1, true); 


if (image != null) { 
int iwidth = image.getWidth (this) ; 
int iheight = image.getHeight (this) ; 
if (iwidth != -1 && iheight != -1) { 
// Draw it to the center. 
g.drawImage (image, (w-iwidth) /2, (h-iheight)/2, iwidth, 
iheight, this); 


public Dimension getMinimumSize() { 
return new Dimension (400,300); 


public Dimension getPreferredSize() { 
return getMinimumSize(); 


// This method will fetch images from the current directory or 
// CLASSPATH. 
Image loadImage (String imgPath) { 


Image img = null; 
URL imgURL = null; 
MediaTracker media = new MediaTracker (this) ; 


// First try from current directory. 
ClassLoader cl = getClass().getClassLoader (); 
if (cl != null) { 

imgURL = cl.getResource (imgPath) ; 
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// If not found, try CLASSPATH. 
if (imgURL == null) { 
imgURL = ClassLoader.getSystemResource (imgPath) ; 
} 
try { 
img = getToolkit() .getImage (imgURL) ; 
} catch (Exception e) { 
e.printStackTrace(); 


} 


try { 
media.addImage(img, 0); 
media.waitForAll (); 
} catch (Exception e) { e.printStackTrace(); } 


return img; 


}//end loadImage method 
} 


When you run the Xlet, as described in Chapter 2, “Running the Sample 
Programs,” the following window appears: 


“XlofRunner — SimpleXletDe 


The following sections describe this Xlet. 


Importing the Xlet Package 
All Personal Profile Xlets rely on classes in the following package: 
import javax.microedition.xlet.*; 


This package contains interfaces used by Xlets and Xlet Managers to communicate. 
Through the Xlet and XletContext interfaces in this package, the Xlet Manager 
can manage the lifecycle of one or more Xlets. 
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Writing a Constructor and Implementing the Xlet 
Interface 


All Xlets must provide a public, no-argument constructor and implement the Xlet 
interface in the Xlet package: 


public class SimpleXlet extends Component implements Xlet { 


The Xlet Manager calls the constructor to create the Xlet. The xlet interface allows 
an Xlet Manager to control the Xlet lifecycle, including initializing, starting, 
pausing, and destroying an Xlet. Each Xlet must implement the following xlet 
interface methods for the Xlet Manager to call: 


m initXlet — Initializes the Xlet and changes the lifecycle state to Paused. It is 
called only once. 


m startXlet — Changes the lifecycle state to Active. 
m™ pauseXlet — Changes the lifecycle state to Paused. 
m destroyXlet — Changes the lifecycle state to Destroyed. It is called only once. 


When the Xlet Manager calls one of these methods, and the call returns 
successfully, the Xlet state is officially “changed.” The Xlet can contain code in the 
method bodies that performs the processing necessary to enter that state. For 
example, it might have code that opens a network connection, reads user input, 
paints an image on the screen, releases resources, and so on. If an Xlet is made of 
multiple classes, it is through the class that implements the X1let interface that the 
Xlet Manager accomplishes lifecycle changes. 


Initializing the Xlet and Obtaining the 
XletContext 


After the Xlet Manager creates an Xlet, it initializes it with an initXlet call. 
During Xlet initialization, you might perform operations such as getting the 
container to display a user interface, opening a network connection, populating 
properties with values, and other tasks that are best done at this time. This method 
is called only once during the lifecycle of an Xlet. If the call returns successfully, the 
Xlet is placed in the Paused state. 


Each Xlet has its own XletContext. The context is passed to an Xlet by the Xlet 
Manager when the Xlet is initialized: 
public void initXlet (XletContext context) { 


Part of the xlet package, the XletContext interface provides methods that 


a Allow an Xlet to discover information about its runtime environment (the 
system on which it’s running, outside of the Xlet itself). 


a Acontext can optionally store properties. For example, the UNIX shell has 
environment variables with settings that are unique to a particular user on a 
computer, such as the printer used. Similarly, an Xlet might need information 
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from settings in its environment, for instance, a user name stored in a UserName 
property. The Xlet Manager communicates information about the environment 
to the Xlet through the getXletProperties method. An Xlet can get 
properties through command-line arguments or another mechanism. Let an Xlet 
change its own state to Paused or Destroyed, or ask the Xlet Manager to make it 
Active, as described later in “Xlet-Initiated State Changes” on page 54.” 


a Allow an Xlet with graphical components to get a container, as illustrated in the 
sample X\let. 


Note that you must store a reference to the context to use the context after 
initialization, such as to set or retrieve any property values. 


The sample Xlet displays an image as its Active function. During initialization, the 
Xlet loads the image, which is similar to commonly used JDK programming 
techniques, except it gets the parent container first: 


try { 
rootContainer = context.getContainer (); 
rootContainer.setSize (640,480); 
rootContainer.setLayout (new BorderLayout ()); 
rootContainer.setLocation(0,0); 
rootContainer.add("North",this) ; 
rootContainer.validate(); 
image = loadImage ("images/duke.gif"); 
} catch (Exception e) { e.printStackTrace(); } 


The Xlet calls the Xlet Context .getContainer method to get the parent 
container for the Xlet to put its AWT components in. Xlets without a graphical 
representation do not need to call this method. If successful, this method returns an 
instance of java.awt.Container that is initially invisible, with an arbitrary size 
and position. It’s the Xlet’s responsibility to make the container visible, in this case, 
when the Xlet becomes Active. 


The object returned by the get Container method will either be an instance of 
Frame or a Container within a Frame. The sample Xlet Manager does the latter. 


Personal Profile permits multiple application-created Frames at a time. In the case 
of Xlets, the Frame instance is created in advance by the Xlet Manager; if an Xlet 
attempts to create a Frame on it own, it will fail. ArFrame can contain multiple 
Xlets. For example, for a television application, the Frame could encompass the 
entire screen and be transparent so the underlying television show is visible. 


If the getContainer method is called multiple times within the same Xlet 
instance, the same Container instance is returned each time (you wouldn’t get a 
new container each time). Each Xlet instance has just one container and just one 
XletContext instance, which are not shared with other Xlet instances. Note that 
platforms may have a limit on how many graphical Xlets they will support at a 
time for display, for example, the platform may support just one. However, at least 
the first call to this method platform-wide is guaranteed to succeed. (If the platform 
is in a state where it doesn't want any Xlets displaying, the Xlet Manager would 
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most likely either not create any Xlets at all or destroy the ones that it already has.) 
If policy or screen real estate does not permit a Container to be granted to the 
Xlet, the Xlet throws an UnavailableContainerException. 


When the Xlet sets the size and position of the parent container, the parent 
container attempts to change its shape, but the calls may fail silently or make 
platform-specific approximations. So you can’t assume that you can set the 
container size and position in every case. To discover if a request to change the size 
or position has succeeded, the Xlet should query the container for the result. 


In the sample, the paint and loadImage methods use common Java 
programming techniques, without any Xlet-specific code. 


Starting the Xlet and Getting the Container 


After initialization, the Xlet can be started: 
public void startXlet() { 


Within the startXlet method, the Xlet prepares to enter its Active state where it 
performs the functions it was designed for. If the Xlet has a graphical user 
interface, the work done in the method body is usually small, such as painting the 
user interface on the screen or re-initiating some activity. A non-graphical Xlet 
would simply start whatever processing it does. For example, if an Xlet performed 
some sort of batch job and the batch processing took some time, it could begin its 
work, return from the startXlet method (this method is supposed to return 
quickly), and when the batch work was finished, it could notify the Xlet Manager 
that it was Destroyed. 


Calling setVisible (true) makes the container, and the image inside it, visible: 
rootContainer.setVisible (true); 


After the call successfully returns, the Xlet is in the Active state and the image 
appears on the screen. (The window appeared during initialization.) 


Pausing the Xlet 


After starting an Xlet, it can move to the Paused state, after which it can be started 
again, as many times as needed. To pause an Xlet in the Active state, the Xlet 
Manager calls pauseXlet: 


public void pauseXlet() { 
rootContainer.setVisible (false) ; 


} 


If the call successfully returns, the Xlet enters the Paused state. In this case, before 
pausing, the container (and image) are made invisible. If the Xlet is started again, 
the container would be made visible again. 
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An Xlet must implement the pauseXlet method. The Xlet Manager is free to call 
this method at any time while the Xlet state is Active, or not call it at all. 


Destroying the Xlet 


An Xlet Manager can destroy an Xlet at any time by calling the dest royXlet 
method: 


public void destroyXlet (boolean unconditional) { 
rootContainer.remove (this); 
image = null; 


} 


If the call successfully returns, the Xlet enters the Destroyed state, and this instance 
will not be run again. In the SimpleXletDemo code, before the Xlet is destroyed, the 
container and image are destroyed. 


An Xlet must implement the dest royXlet method, and the Xlet Manager is free 
to call this method at any time. When you run SimpleXletDemo by using the Xlet 
Manager included with the reference implementation, it’s called in response to a 
user action: the user either chooses the Destroy menu item or closes the Frame; it 
doesn’t call destroyXlet (or pauseXlet) on its own, without a user action. 


To clean up, an Xlet might remove any Xlet display from the screen, close I/O and 
network connections, and perhaps save the state to persistent storage, if this is 
supported. 


Xlet Lifecycle and States 


Java applications that use the Xlet application lifecycle are called Xlets. The Xlet 
lifecycle model defines the interactions between an Xlet and its environment 
through 


m astate machine 
a a definition of the lifecycle states 
m an API that signals changes between these states 


An Xlet Manager is required if you want to run Xlets. However, other than some 
basic requirements, an Xlet Manager’s precise behavior is implementation-specific. 
The four Xlet states defined in the lifecycle are 


m Loaded — The Xlet Manager successfully calls new to create the Xlet. The Xlet 
code is loaded, but not initialized. Each Xlet instance enters this state only once. 


a Paused — The Xlet is initialized and at rest, with minimal usage. 
m Active — The Xlet is executing normally and providing its service. 
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ms Destroyed — The Xlet has released resources and terminated. Each Xlet instance 
enters this state only once. The Xlet should perform its own cleanup. 


Xlet Manager Control of States 


The Xlet Manager controls the lifecycle of an Xlet by loading it, keeping track of its 
state at all times, and calling methods on the Xlet that cause state changes. If the 
Xlet Manager calls a method that initiates a state change, the Xlet signals the 
success or failure of the change by the return value of the method. After the call 
returns successfully, the Xlet state is considered “changed” by the Xlet Manager. 
The lifecycle states allow the Xlet Manager to manage the activities of multiple 
Xlets within a runtime environment, selecting which Xlets are active at a given time 
and removing Xlets when they are destroyed. 


Xlet Interface Methods 


Each Xlet must implement the following xlet interface methods, which are called 
by the Xlet Manager: 


Xlet Lifecycle Method Action 


void initXlet (XletContext Signals the Xlet to initialize itself and enter the 

context) Paused state, so it’s prepared to provide its service 
quickly. This method is called only once. If the Xlet 
can’t initialize, it throws an 
XletStateChangeException and the Xlet Manager 
immediately destroys it. 


void startXlet () Signals the Xlet to start providing service and enter 
the Active state. Usually, only the Xlet knows if it’s 
adequately providing the service it was designed for, 
so an Xlet Manager can’t “force” it to provide service, 
but only let the Xlet know that it’s permitted to do so. 
If the Xlet can’t start, it throws an 
XletStateChangeException. 


void pauseXlet () Signals the Xlet to stop providing service and enter 
the Paused state. 
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Xlet Lifecycle Method Action 


void destroyXlet (boolean Signals the Xlet to terminate and enter the Destroyed 

unconditional) state. If the methods initXlet, startXlet, or 
pauseXlet terminate with an uncaught exception or 
error, then the Xlet Manager will immediately destroy 
the Xlet unconditionally by invoking its 
destroyXlet method. In the method body, you can 
add cleanup code, including releasing resources (such 
as I/O or network connections), removing graphical 
displays, or saving preferences and application state 
(as opposed to lifecycle state), for example. The Xlet 
can request that it not enter the Destroyed state by 
throwing an Xlet StateChangeException; if the 
unconditional flag is false, the Xlet Manager will most 
likely honor that request. 


You can think of initXlet and destroyXlet asa pair, and startXlet and 
pauseXlet as a pair. In general, what you do in initXlet, you destroy in 

dest royXlet; what you start in start Xlet, you pause in pauseXlet. initXlet 
and destroyXlet are called only once, while start Xlet and pauseXlet can be 
called multiple times. So, for example, you might want to open a thread in 
initXlet, because if you opened the thread in startXlet, you would recreate it 
every time startXlet was called. 
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Xlet State Diagram 


The following state diagram shows the relationship between Xlet states and the 
Xlet interface methods: 


new initXlet 
ne at Loaded Pm Paused 
destroyXlet destroyXlet — startXlet pauseXlet 
D i Acti 
lestroyed destroyXlet ctive 


Xlet Skeleton Code Snippet 


The following skeleton code snippet summarizes the basic parts of an Xlet 
implementing the Xlet interface: 


public class MyXlet implements javax.microedition.xlet.Xlet { 


public void initXlet( javax.microedition.xlet.XletContext ctx) 
throws javax.microedition.xlet.XletStateChangeException { 


} 


public void startXlet () 
throws javax.microedition.xlet.XletStateChangeException { 


} 


public void pauseXlet() { 
} 


public void destroyXlet ( boolean unconditional) 
throws javax.microedition.xlet.XletStateChangeException { 


} 


Xlet Lifecycle Example 
A typical scenario might be the following sequence: 
1. The Xlet Manager obtains the Xlet’s class definition through a class loader. 


2. The Xlet Manager creates a new instance of the Xlet. 


To do so, the Xlet Manager successfully calls the default, no-argument, Xlet 
constructor. The Xlet instance is in the Loaded state. 
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3. The Xlet Manager initializes the Xlet and creates the XletContext for the Xlet. 


The Xlet Manager successfully calls initXlet, and passes it the XletContext 
object. The Xlet instance is now in the Paused state. Through code in the initXlet 
method body, the Xlet acquires resources it needs. It might open a new thread to 
retrieve stock quotes, for example. 


4. The Xlet Manager decides that it’s an appropriate time for the Xlet to perform its 
service, so it starts the Xlet. 


For example, for an Xlet displayed on a television through a set-top box, the user 
might press a button on the remote control that signals the Xlet Manager to start 
the Xlet. 


The Xlet Manager successfully calls start Xlet. In the method body, it might start 
displaying stock quotes received from the thread that retrieves stock quotes, for 
example. The Xlet instance is now in the Active state, where it performs its service 
(such as showing stock quotes). 


5. The Xlet Manager no longer needs the Xlet to perform its service, so it pauses the 
Xlet. 


The Xlet Manager successfully calls pauseXlet. The Xlet stops performing its 
service, and might choose to release some resources it currently holds. The Xlet 
instance is in the Paused state. 


6. The Xlet Manager needs the Xlet to perform its service again. 


The Xlet Manager successfully calls start Xlet. The Xlet instance is in the Active 
state again. 


7. The Xlet Manager determines that the Xlet is no longer needed, or must make 
room for a higher-priority Xlet, so it destroys the Xlet. 


The Xlet Manager successfully calls destroyXlet. In the dest royXlet method 
body, the Xlet performs clean-up operations, and optionally saves the user 
preferences and application state (as opposed to Xlet lifecycle state). The Xlet 
instance is now in the Destroyed state. 


8. The Xlet Manager prepares the Xlet for garbage collection. 


The Xlet Manager drops all references to the Xlet so it can later be garbage 
collected. 


Xlets and Finalization 


The Java language provides a mechanism called finalization that allows objects to 
perform some cleanup just before they are garbage collected. The finalizer on an 
object will not be called until all references to the object have been discarded and 
the object is ready to be garbage collected. The Java language specification states 
that programmers should never depend on a finalizer being called. Note that in the 
Xlet interface, the destoyXlet method is called on an Xlet shortly before it’s to 
be destroyed. The intent of the two methods is similar, but programmers can 
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assume that the dest royxlet method will be called. If an Xlet must typically do 
cleanup at the end of normal execution, the Xlet should use its dest royXlet 
method; in most cases, the finalizer should be empty. 


Xlet Lifecycle Methods, Synchronization, and Threads 


In general, Xlets should declare their lifecycle methods (the methods implementing 
the Xlet interface) as synchronized. Although this is not done in the 
SimpleXletDemo sample, a more sophisticated Xlet would do this. Synchronizing 
the methods is not done in the Xlet interface method signatures because interface 
methods can’t be declared synchronized in the Java language. By declaring these 
methods synchronized, a lock will be acquired on the Xlet object interface when 
one of the lifecycle methods is called. This will have the effect of blocking other 
calls to the Xlet’s other method's lifecycle methods. Xlets can also benefit from 
acquiring a lock on themselves before calling the lifecycle methods on their 
XletContext. A well-designed Xlet Manager will create individual threads to call 
the lifecycle methods on Xlets. 


Xlet-Initiated State Changes 


An Xlet can influence its own state by 

m changing its state to Paused or Destroyed, 

m asking to become Active, or 

m objecting to being Initialized or Destroyed, or becoming Active. 


An Xlet can change its own state to Paused or Destroyed through XletContext 
interface methods. First, the Xlet would perform the processing necessary for it to 
be considered Paused or Destroyed, probably similar to that done in the 
pauseXlet and dest royXlet methods. After, it must inform the Xlet Manager of 
the state change by calling a method on the XletContext interface, either 
notifyPaused and not ifyDestroyed. For example, the Xlet may determine that 
it should be Paused when it’s not interacting with a user or performing other 
functions that it normally would in its Active condition. You could think of it as 
similar to iconifying a window in a desktop operating system, where there is no 
longer a visual representation of the application. The Xlet may determine that it is 
Destroyed because the user specified that they wanted to exit the application. In 
these cases, it would be appropriate for the Xlet to change its own state because it 
knows more information than the Xlet Manager does. The state is considered 
“changed” when the not ifyPaused and not ifyDestroyed methods are entered. 


An Xlet can also ask to become Active by invoking an Xlet Context method: 
resumeRequest. If the Xlet Manager agrees, it calls startXlet. 


If the Xlet Manager calls dest royXlet, the Xlet can request that it not enter the 
Destroyed state by throwing an XletStateChangeException. This is only a 
valid response if the unconditional flag (an argument to the call) is set to false. 
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In this case, the Xlet Manager honors the request and may call the dest royXlet 
method again at a later time. If the flag is set to true, however, the Xlet is assumed 
to be in the Destroyed state regardless of how this method terminates. 


XletContext Interface Methods and States 


An Xlet uses the following methods on the Xlet Context interface to convey state 
information to the Xlet Manager: 


XletContext Method Action 
public void Notifies the Xlet Manager that the Xlet has entered 
notifyDestroyed() the Destroyed state and that all resources held by the 


Xlet are ready for garbage-collection. Before calling 
this method, the Xlet should have performed the 
same operations as its dest royXlet method. 


public void Notifies the Xlet Manager that the Xlet has entered 

notifyPaused () the Paused state. Before calling this method, the Xlet 
should have performed the same operations as its 
pauseXlet method. 


public void Notifies the Xlet Manager that the Xlet would like to 

resumeRequest () become Active. You can use this method to help the 
Xlet Manager determine which Xlets to move to the 
Active state. If the Xlet Manager decides to fulfill the 
request, it calls start Xlet ona different thread than 
the one used to call resumeRequest. 


Xlet Lifecycle Example with Xlet-Initiated State Changes 


An Xlet is often best able to determine whether it is able to perform properly. So an 
Xlet can determine whether certain state changes are needed. A typical scenario 
might be the following sequence: 


. The Xlet Manager obtains the Xlet’s class definition through a class loader. 


. The Xlet Manager creates a new instance of the Xlet. 

To do so, the Xlet Manager successfully calls the default, no-argument, Xlet 
constructor. The Xlet instance is in the Loaded state. 

. The Xlet Manager initializes the Xlet and creates the XletContext for the Xlet. 


The Xlet Manager successfully calls initXlet, and passes it the XletContext 
object. The Xlet instance is now in the Paused state. Through code in the initXlet 
method body, the Xlet acquires resources it needs. It might open a new thread to 
retrieve stock quotes, for example. 
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4, The Xlet Manager decides that it’s an appropriate time for the Xlet to perform its 
service, so it starts the Xlet. 


For example, for an Xlet displayed on a television through a set-top box, the user 
might press a button on the remote control that signals the Xlet Manager to start 
the Xlet. 


The Xlet Manager successfully calls start Xlet. In the method body, it might start 
displaying stock quotes received from the thread that retrieves stock quotes, for 
example. The Xlet instance is now in the Active state, where it performs its service 
(such as showing stock quotes). 


5. The Xlet determines that it no longer needs to perform its service for now, so it 
pauses itself. 


The Xlet performs the operations necessary to place it in the Paused state, and then 
informs the Xlet Manager by calling not ifyPaused. 


For example, if an Xlet retrieves and displays stock quotes, but it no longer is able 
to retrieve them, it might display the most recent quotes it has until it determines 
that the quotes are too old. At this point, it might pause itself. 

6. The Xlet determines that it needs to perform its service again. 

The Xlet calls resumeRequest. The Xlet Manager agrees that the Xlet can be 
started again, so it successfully calls start Xlet. The Xlet instance is in the Active 
state again. 

7. The Xlet Manager tries to destroy the Xlet conditionally, but the Xlet objects. 
The Xlet Manager calls dest royXlet. The Xlet throws an 
XletStateChangeException, and since the unconditional flag is false, the Xlet 
Manager agrees to keep the Xlet Active. 

8. The Xlet determines that it has completed its task and is no longer needed. 


The Xlet performs the processing necessary to place it in the Destroyed state, and 
then informs the Xlet Manager by calling not ifyDest royed. 


Another scenario might be that the Xlet determines that there is a problem and it 
has no chance of ever performing its service again, so it decides it must be 
terminated. 

9. The Xlet Manager prepares the Xlet for garbage collection. 


The Xlet Manager drops all references to the Xlet so it can later be garbage 
collected. 


Inter-Xlet Communication and State Changes 
An Xlet can’t start another Xlet, or force another Xlet to change its state. However, 


through Inter-Xlet Communication, an Xlet can cooperate and communicate with 
other Xlets, and ask for a state change. IXC is described next. 
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Implementing Inter-Xlet 
Communication (IXC) 


Inter-Xlet Communication allows two or more Xlets to communicate by allowing 
one to invoke the methods of another. It uses a set of new classes and interfaces 
specified in Personal Profile, but the idea is based on Remote Method Invocation 
(RMI), which is a part of the JDK. The difference between RMI and IXC is that RMI 
allows two applications using different VMs to talk, while IXC allows two Xlets in 
the same VM (but with a different class loader) to talk. The syntax for using IXC is 
similar to RMI: you still implement a remote interface and register it to a Registry. 


One slight difference is how you find the Register class. RMI uses 
java.rmi.Naming and java.rmi.registry.LocateRegistry to finda 
Registry, but IXC gets it directly from the 
javax.microedition.xlet.ixc.IxcRegistry class. 


For more information on RMI, see the tutorial: 
http://java.sun.com/j2se/1.4/docs/guide/rmi/getstart.doc.html 


In personal/src/share/personal /demo/IXCDemo is an example of two Xlets 
that communicate with each other through IXC. It is loosely based on a flight 
simulator, where a server maintains the position of an airplane, and a client 
receives position updates. 


The client is in ixcXlets/clientXlet (IXCDemo.ixcXlets.clientXlet 
package), and the server is in ixcXlets/serverXlet 
(IXCDemo.ixcXlets.serverXlet package). The directory shared contains data 
type definitions of the objects that are shared between the two. All of the classes in 
shared must be a part of each Xlet. Since Xlets have separate class loaders, this 
means that two copies of each shared class are loaded. 


The server Xlet binds itself to the IxcRegistry with two instances of the plane 
implementation. The client Xlet gets a reference to this registry and the two 
instances of the plane implementation. At this point, both instances of the plane 
implementation are equal as they have not been modified (there hasn’t been a 
position or speed change). 


The client Xlet then sets the acceleration and the heading of the first plane 
implementation instance. The two plane implementations are no longer equal as 
the speed and heading of the first has been modified. 


The server receives the acceleration and heading information and the plane 
implementation position is updated every 2 seconds for 20 seconds. The client Xlet 
is a registered listener of the first plane implementation and is notified of the new 
position. 


This demonstrates the Inter-Xlet Communication between two Xlets running in the 
same instance of the VM, but each with a different class loader. 
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When you run the Xlet, the display looks something like this: 


Manager: client created 

client: constructed 

Manager: server created 

PlaneClient starting... 

PlaneClient looking for import registry. 
Planeclient waiting for the server for 2 second 
server: constructed 


PlaneClient adding self as listener. 

PlaneImp] gets new listener IXCDemo.ixcXlets.clientxXlet.PlaneClient@f4264f 
Other plane: IXCDemo.ixcXlets.serverXlet.PlaneImp]<speed=0.0, heading=0.0, pos 
jition=Position(€x=0.0, y=0.0)> 

Other equals primary? true 

PlaneClient setting speed and heading 

PlaneServer accelerates by 2.7 

PlaneServer turns by 1.0471975511965976 

Other equals primary? false 


You might need to press Control+C to exit. 


IXCDemo Package 


This package contains the class IxCDemo.1XCMain. This class instantiates, 
initializes, starts, and destroys the client and server Xlets. 


IXCMain imports java.io. IOException (used to catch IOException when 
creating the Xlets) and com.sun.xlet .XletManager, and 
com.sun.xlet.XletLifecycleHandler. See “A Simple Xlet Manager” on 
page 74,” for more information on the Xlet Manager: Xlet Context Impl. 


The main method creates two instances of Xlet LifecycleHandler through 
XletManager: client and server. (There are two Xlets, and each Xlet is managed 
through an instance of XletLifecycleHandler.) The paths to the PlaneClient 
and PlaneServer are then hardcoded and the Xlets are created using these paths 
with the Xlet Manager’s createXlet method. Both client and server Xlets are then 
initialized. The client is then started and there is a pause of 1 second before the 
server is started. 


The two Xlets run for 20 seconds before the client Xlet is destroyed. After 5 seconds 
(to allow the client to fully shut down and free any resources used by it), the server 
is then destroyed and the application exits. 
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Following is the IXCMain code: 


package IXCDemo; 


// To catch IOException when creating Xlets. 
import java.io.IOException; 


// To use Xlet Manager methods and createXlet method. 
import com.sun.xlet.XletLifecycleHandler; 


import com.sun.xlet.XletManager; 


[** 


* Main launching class. This is a minimalistic test that hard-codes 
* the launching of two Xlets. It then waits 20 seconds, destroys the 


* client, waits 5 seconds, destroys the server, and terminates. 


*/ 
public class IXCMain { 


private static void sleep(long delay) { 
long goal = System.currentTimeMillis() + delay; 
while (delay > 0) { 
try { 
Thread.sleep (1000); 
} catch (InterruptedException ignored) { 


} 


delay = goal - System.currentTimeMillis(); 
} 
} 
public static void main(String args[]) { 
XletLifecycleHandler client = null; 
XletLifecycleHandler server = null; 
try { 
// Paths to PlaneClient and PlaneServer. 
String pathl[] = {"IXCDemo/ixcXlets/clientXlet"}; 
String path2[] {"IXCDemo/ixcXlets/serverXlet"}; 


// Create the client. 


client = XletManager.createXlet ("IXCDemo.ixcXlets. 


clientXlet.PlaneClient", pathl, null); 
System.out.printin("Manager: client created"); 


// Create the server. 


server = XletManager.createXlet ("IXCDemo.ixcXlets. 


serverXlet.PlaneServer", path2, null); 


System.out.printlin("Manager: server created"); 


} catch (IOException ex) { 
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ex.printStackTrace(); 
System.exit (1); 


// Call the Xlet Manager’s postInitXlet method to initialize 
// the Xlets. 

client.postInitXlet (); 

server.postInitXlet (); 


// Call the Xlet Manager’s postStartXlet method to start the 
// client Xlet. Then pause 1 second to wait for the server 
// to start. 

client .postStartXlet (); 

sleep (1000); 

server.startXlet (); 


// Run for 20 seconds before destroying the client. 
sleep (20000) ; 


// Call the Xlet Manager’s postDestroyXlet method to destroy 
// the client. 

client .postDestroyXlet (true) ; 

System.out.printin("Manager: client destroyed"); 

client = null; 


// After 5 seconds (to allow the client to fully shut down 
// and free any resources used by it), the server is destroyed 

// and the application exits. 

sleep (5000); 

server.postDestroyXlet (true); 

server = null; 

System.out.printin("Manager: server destroyed"); 


System.out.printin("Manager exiting"); 


IXCDemo.shared Package 


This package contains interfaces that are required by the client and the server Xlets. 
It contains: 


mw IxXCDemo.shared.Plane — This interface represents an airplane, with a 
position, heading, and speed. It has various methods to allow access to the 
speed, heading, and position with other methods to also set these variables. 


m IXCDemo.shared.PlaneListener — This interface allows interested parties 
to register for notifications when a plane's postion changes. 
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mw IxXCDemo.shared.Position — This interface represents a 2D position with 
float coordinates. It is serializable (extends java.io.Serializable) so it can 
be serialized and passed between the client and server. 


Plane Interface 


//Representation of an airplane with a position, heading, and speed 


package IXCDemo.shared; 


public interface Plan xtends java.rmi.Remote { 


public float getSpeed() 
throws java.rmi.RemoteException; 


// Get the heading, in degrees. 
public double getHeading() 
throws java.rmi.RemoteException; 


public Position getPosition() 
throws java.rmi.RemoteException; 


public void accelerate(float deltavV) 
throws java.rmi.RemoteException; 


public void turn(double delta) 
throws java.rmi.RemoteException; 


public void addListener(PlaneListener 1) 
throws java.rmi.RemoteException; 


public void removeListener(PlaneListener 1) 
throws java.rmi.RemoteException; 


PlaneListener Interface 


// Interface that allows interested parties to register for 
// notifications when a plane’s position changes. 


package IXCDemo.shared; 


public interface PlaneListener extends java.rmi.Remote { 


public void positionChanged(Position newPos) throws 
java.rmi.RemoteException; 
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Position Interface 


// Represents a 2D position with float coordinates. 
package IXCDemo.shared; 
public class Position implements java.io.Serializable { 
static final long serialVersionUID = -1510071578429305515L; 


private float x; 
private float y; 


public Position(float x, float y) { 
this.x = x; 
this.y = y; 


public Position(Position p) { 
this(p.x, p.y); 


public String toString() { 
return "Position(x=" + x +", y=""+ y + ")"; 


public float getx() { 
return x; 


public float getY() { 
return y; 


public int hashCode() { 
return Float.floatToIntBits(x) * Float.floatToIntBits(y); 


public boolean equals(Object other) { 
if (! (other instanceof Position)) { 
return false; 


} 
Position po = (Position) other; 
return x == po.x && y == po.y; 


IXCDemo.ixcXlets.clientXlet Package 


This package contains IXCDemo.ixcXlets.clientXlet.PlaneClient. 
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PlaneClient imports: 


mw javax.microedition.xlet.Xlet and 
javax.microedition.xlet.XletContext — necessary for all Xlets 


m@ javax.microedition.xlet.ixc.IxcRegistry, 
java.rmi.NotBoundException, and java.rmi.NotBoundException — 
necessary to allow IXC to work and to catch possible IXC exceptions that may 
occur. 


m IXCDemo.shared.*— necessary for common classes required by both client 
and server 


PlaneClient implements Xlet and PlaneListener (so the PlaneClient can register 
as a listener of a plane implementation object). 


PlaneClient includes an instance of Xlet Context (needed by all Xlets), a variable 
specifying if the PlaneClient Xlet has started, and an instance of Plane. 


The constructor merely prints that the client has been constructed. 
The initXlet method obtains a reference to the XletContext. 
On starting the Xlet, the variable started is set to true. 


PlaneClient next attempts to obtain a reference to the IxcRegistry through the 
XletContext and waits 2 seconds for the server to start and register itself on the 
IxcRegistry associated with this context. 


PlaneClient then obtains a reference to the first plane implementation registered by 
the server on the IxcRegistry. PlaneClient adds itself as a listener to this object. 
PlaneClient also obtains a reference to the second plane implementation registered 
by the server on the IxcRegistry. 


PlaneClient then sets the heading and acceleration of the first plane 
implementation object. It can be seen that the first and second plane 
implementations are not equal since this change has occurred. 


The PlaneClient is then notified of further updates to the plane position from the 
plane implementation object. The client displays that it has been notified through 
the postionChanged (Position newPos) method. 


On the call to dest royXlet from IXCDemo.IXCMain, PlaneClient removes itself 
as a listener to the first plane implementation object. 


Following is the client code: 


// Client updates its own position, and relays it back to the server. 
// Demonstrates communication between server and client. 


package IXCDemo.ixcXlets.clientXlet; 
// For Xlets. 


import javax.microedition.xlet.Xlet; 
import javax.microedition.xlet.XletContext; 
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// For 
import 
import 
import 


IXC. 
javax.microedition.xlet.ixc.IxcRegistry; 
java.rmi.NotBoundException; 
java.rmi.RemoteException; 


// Interfaces shared by client and server. 


import 


IXCDemo. shared.*; 


// PlaneClient implements Xlet and PlaneListener (so the PlaneClient 
// can register as a listener of a plane implementation object). 
public class PlaneClient implements Xlet, PlaneListener { 


// PlaneClient includes an instance of XletContext (needed by 
// all Xlets), a variable specifying if the PlaneClient Xlet has 


// 


started, and an instance of Plane. 


private XletContext context; 
private boolean started = false; 
private Plane plane; 


// The constructor merely prints that the client has been 
// constructed. 
public PlaneClient() { 


System.out.printin("client: constructed"); 


// Implement Xlet.initXlet, which the Xlet Manager calls to 
// initialize the Xlet. Obtain a reference to the XletContext. 
public void initXlet (XletContext context) { 


this.context = context; 


// Implement Xlet.startXlet, which the Xlet Manager calls to 

// start the Xlet. On starting the Xlet, the variable started is 
// set to true. 

public void startXlet() { 


System.out.printin("PlaneClient starting..."); 
synchronized(this) { 
if (started) { 
return; 
} 


started = true; 


// PlaneClient attempts to obtain a reference to the 
// IxcRegistry through the XletContext and waits 2 seconds 
// for the server to start and register itself on the 
// IxcRegistry associated with this context. Note that the 
// start method is only called once (hardcoded through 
// the IXCMain class). 
try { 
System.out.printlin("PlaneClient looking for import 
registry."); 
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IxcRegistry r = IxcRegistry.getRegistry (context) ; 


System.out.printin("PlaneClient waiting for the server 
for 2 seconds"); 
Thread.sleep (2000) ; 


// PlaneClient then obtains a reference to the first 

// plane implementation registered by the server on the 
// IxcRegistry. PlaneClient adds itself as a listener to 
// this object. 

System.out.printin("PlaneClient looking for plane."); 


plane = (Plane) r.lookup(""); 
System.out.printin("PlaneClient adding itself as 
listener."); 


plane.addListener (this); 


// PlaneClient also obtains a reference to the second 
// plane implementation registered by the server on the 
// IxcRegistry. 


Plane other = (Plane) r.lookup ("other") ; 
System.out.printlin("Other plane: " + other); 
System.out.printlin("Other equals primary? " + 


other.equals (plane) ); 


// PlaneClient then sets the heading and acceleration 
// of the first plane implementation object. The first 
// and second plane implemenations are not equal since 
// this change has occurred. 
System.out.printin("PlaneClient setting speed and 
heading") ; 
plane.accelerate((float) 2.7); 
plane.turn(Math.PI / 3.0); 
System.out.printlin("Other equals primary? " + 
other.equals (plane) ); 
} catch (InterruptedException e) { 
System.out.printin("PlaneClient interruped") ; 
context .resumeRequest (); 
} catch (NotBoundException ex) { 
System.out.printin("Server object not found"); 
ex.printStackTrace(); 
context .notifyDestroyed(); 
return; 
} catch (RemoteException ex) { 


System.out.printin("Client sees unexpected remote 
exception") ; 

ex.printStackTrace(); 

context .notifyDestroyed(); 

return; 
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// Implement Xlet.pauseXlet. 
public void pauseXlet() { 
} 


// On the call to Xlet.destroyXlet from IXCDemo.IXCMain, 
// PlaneClient removes itself as a listener to the first plane 
// implementation object. 
public void destroyXlet (boolean unconditional) { 
try { 
plane.removeListener (this) ; 
} catch (RemoteException ex) { 
ex.printStackTrace(); 


/* sssssssssss== Method from PlaneListener 


public void positionChanged(Position newPos) { 
System.out.printlin("Client sees new position: " + newPos); 


IXCDemo.ixcXlets.serverXlet Package 


This package contains: 


m IXCDemo.ixcXlets.serverXlet.PlaneServer 
m IXCDemo.ixcXlets.serverXlet.PlaneImpl 


These classes import much the same classes as PlaneClient for the same reasons. 


PlaneServer 


The purpose of this class is to register the two plane implementations with the 
IxcRegistry associated with the context. It also starts a separate thread that 
continually calls on the tick method of the PlaneImp1 class until it is interrupted 
or signalled to be stopped. 


PlaneServer implements Xlet and Runnable (see the Personal Profile specification 
for more information on java.lang.Runnable). 


PlaneServer includes an instance of Xlet Context (needed by all Xlets), and 
separate variables specifying if the PlaneServer Xlet has started, if it is running, and 
if it has been set to stop running. It also includes an instance of PlaneImp1l. 


The constructor merely prints out that the server has been constructed. 


The initXlet method obtains a reference to the XletContext. 
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On starting the Xlet, a check is made as to whether the Xlet is already running and, 
if not, the variable started is set to true. 


The run method is then called through the t . start call. This run method will 
loop until it has been interrupted or signalled to be stopped through the 
pleaseStop variable. With each loop, the tick method of the plane 
implementation is called. 


Back in the startXlet method, PlaneServer registers two plane implementations 
with the IxcRegistry associated with the context. 


A call to pauseXlet or dest royXlet will cause the running thread to stop. 


Following is the server: 


package IXCDemo.ixcXlets.serverXlet; 


// Import the Xlet packages needed by Xlets. 

// Alternatively, can import just javax.microedition.xlet.* 
import javax.microedition.xlet.Xlet; 

import javax.microedition.xlet.XletContext; 


// Import the package where the IXC registry comes from. 

// You register the server on the registry, and later the client 
// finds the server on the registry. 

import javax.microedition.xlet.ixc.IxcRegistry; 


// Import RMI exceptions. 

import java.rmi.AlreadyBoundException; 
import java.rmi.RemoteException; 
import java.rmi.AccessException; 


// PlaneServer implements Xlet and Runnable. 
public class PlaneClient implements Xlet, Runnable { 


// PlaneServer includes an instance of XletContext (needed by 
// all Xlets), and separate variables specifying if the 

// PlaneServer Xlet has started, if it is running, and if it has 
// been set to stop running. It also includes an instance of 

// PlaneImpl. 
private XletContext context; 


private boolean running = false; 
private boolean pleaseStop = false; 


// The plane is not started when the Xlet starts. 
private boolean started = false; 


// Create an instance of plane. 
private PlaneImpl planeImpl = new PlaneImpl(); 
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// Create an instance of PlaneServer. The constuctor merely 
// printsthat the server has been constructed. 
public PlaneServer() { 

System.out.printin("server: constructed") ; 


// Implement Xlet.initXlet.Obtain a reference to the XletContext. 
public void initXlet (XletContext context) { 
this.context = context; 


// Implement Xlet.startXlet. Check if the Xlet is already 
// cunning; if not, the variable started is set to true. 
public void startXlet() { 

System.out.printin("PlaneServer was started."); 


boolean wasStarted; 
synchronized(this) { 
pleaseStop = false; 
if (running) { 
return; 
} 
running = true; 
wasStarted = started; 
if (!'!started) { 
started = true; 


} 
// Call the run method, through the t.start call. This run 


// method will loop until it has been interrupted or 
// signalled to be stopped through the pleaseStop variable. 
// With each loop, the tick method of the plane 
// implementation is called. 
Thread t = new Thread(this); 
t.setDaemon (true) ; 
t.start(); 
if (!wasStarted) { 
// PlaneServer registers two plane implementations with 
// the IxcRegistry associated with the context. 
try { 
IxcRegistry r = IxcRegistry.getRegistry (context) ; 


r.bind("", planelImpl) ; 
r.bind("other", new PlaneImpl()); 
} catch (AlreadyBoundException ex) { 
System.out.printin("Server was already registered."); 


ex.printStackTrace(); 
context .notifyDestroyed(); 
return; 
} catch (RemoteException re) { 
System.out.printin("Server cannot contact Registry"); 


re.printStackTrace (); 
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context .notifyDestroyed(); 
return; 


// AK call to pauseXlet or destroyXlet will cause the running 
// thread to stop. 
public void pauseXlet() { 

stopMe () ; 


public void destroyXlet (boolean unconditional) { 
stopMe (); 


private void stopMe() { 
synchronized(this) { 
pleaseStop = true; 
notifyAll(); 


public void run() { 
for (77) { 
synchronized(this) { 
if (pleaseStop) { 
running = false; 
return; 
} 
try { 
wait (2000); 
} catch (InterruptedException ex) { 
Thread.currentThread().interrupt (); 
return;// We’re being killed; bail out 


} 
if (!pleaseStop) { 
planeImpl.tick(); 


PlaneImpl 


The purpose of this class is provide an implementation of the 
IXCDemo. shared. Plane class. 


This class receives a command that sets its heading and speed from the client 
through the server. 
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The server will then call the tick method from the server thread that is running. 
The tick method then updates the position of the plane and then notifies any 
registered listeners (in this case, PlaneClient) of the change. 


Following is the code: 


package IXCDemo.ixcXlets.serverXlet; 
import java.util.Vector; 


import javax.microedition.xlet.Xlet; 

import javax.microedition.xlet.XletContext; 
import java.rmi.RemoteException; 

import IXCDemo.shared.*; 


public class PlaneImpl implements Plane { 


private float speed; 

private double heading; 

private Position position = new Position(0, 0); 
private Vector listeners = new Vector (); 
private long lastTime; 


public float getSpeed() { 
return speed; 


public double getHeading() { 
return heading; 


public Position getPosition() { 
return position; 


public void accelerate(float deltaV) { 
System.out.printin("PlaneServer accelerates by " + deltaV); 
speed += deltaV; 
updatePosition(); 


public void turn(double delta) { 
System.out.printin("PlaneServer turns by " + delta); 
heading += delta; 
updatePosition(); 


public void addListener(PlaneListener 1) { 
System.out.printin("PlaneImpl gets new listener " + 1); 
listeners.addElement (1); 
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public void removeListener(PlaneListener 1) { 
listeners.removeElement (1); 


// The server calls the tick method from the server thread that 
// is running. The tick method updates the position of the 
// plane and then notifies any registered listeners (in this 
// case, PlaneClient) of the change. 
void tick() { 
updatePosition(); 
notifyListeners(); 


// This class receives a command that sets its heading and speed 
// from the client through the server. 


private void updatePosition() { 
synchronized(this) { 
long next = System.currentTimeMillis(); 


long deltaT = next lastTime; 

float x = position.getX() + (float) (speed * 
Math.sin (heading) ); 

float y = position.getY() + (float) (speed * 
Math.cos (heading) ); 


position = new Position(x, y); 
lastTime = next; 
} 
} 
private void notifyListeners() { 
PlaneListener[] 1; 
synchronized(listeners) { 
1 = new PlaneListener[listeners.size()]; 
for (int i = 0; i < l.length; i++) { 
1[i] = (PlaneListener) listeners.elementAt (i); 


for (int i = 0; i < l.length; i++) { 
try { 
System.out.printin("PlaneImpl notifing listener " + 
1[il); 
1[i].positionChanged (position) ; 
} catch (RemoteException ex) { 
ex.printStackTrace(); 
System.out.println("Remote exception, will remove 
listener..."); 
try { 
Thread.sleep (2000) ; 
} catch (InterruptedException iex) { 
Thread.currentThread() .interrupt (); 


} 


System.out.printlin("Removing listener."); 
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removeListener(1[i]); 


public int hashCode() { 
long headingBits = Double.doubleToLongBits (heading) ; 
return position.hashCode () 
“ Float.floatToIntBits (speed) 
“ ((int) (headingBits & (headingBits >>> 32))); 


public boolean equals(Object other) { 

if (this == other) { 
return true; 

} else if (! (other instanceof PlaneImpl)) { 
return false; 

} else { 
PlaneImpl po = (PlaneImpl) other; 
return speed == po.speed && heading == po.heading 
&& position.equals (po.position) ; 


public String toString() { 
return getClass ().getName() + "<speed=" + speed + ", heading=" 
+ heading 
+ ", position=" + position + ">"; 
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CHAPTER 6 


Writing Xlet Managers 


The Personal Profile specification outlines the requirements for an Xlet Manager, 
and the reference implementation provides an example. Other than these basic 
requirements, its precise behavior is implementation-specific. This chapter outlines 
Xlet Manager functions and explains the sample. 


The chapter contains the following sections: 
a “Main Requirements of an Xlet Manager” on page 73 
a “A Simple Xlet Manager” on page 74 


The previous chapter contained important information on Xlets and the Xlet 
lifecycle, which an Xlet Manager manages. You should read that chapter before 
your read this chapter. 


An Xlet Manager is a type of application. For more information on specific 
programming tasks related to writing applications and Xlets, see Chapter 8, 
“Implementing Common Programmatic Features.” To start developing Xlet 
Managers and Xlets quickly, you can develop over the Personal Profile reference 
implementation, as described in Chapter 9, “Using the Reference Implementation 
as a Development Platform.” 


Note that an Xlet Manager is sometimes called an application manager, which is a 
more general term. 


Main Requirements of an Xlet Manager 


The Xlet lifecycle model requires that the Xlet Manager adhere to the following 
principles: 
m An Xlet Manager can change the state of an Xlet. 


The primary purpose of an Xlet Manager is to direct the state changes of an Xlet. 
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a An Xlet can be destroyed at any time. 


An Xlet Manager is the entity that has ultimate control over the Xlets it manages. 
Therefore, the Xlet Manager must be able to destroy the Xlet at any time. 


a The current state of an Xlet will always be known. 


An Xlet Manager keeps track of the states of all Xlets it manages. Xlets should 
notify the Xlet Manager if it changes its state. Xlets can change their own states 
to Paused or Destroyed, but they must notify the Xlet Manager when they do. 
This way, the Xlet Manager can track the state of each Xlet. 


You can think of the Xlet lifecycle model as a “mechanism” as opposed to a 
“policy.” The Xlet lifecycle is primarily concerned with the state machine and legal 
transitions between the states, leaving flexibility as to when the transitions are 
made. The general model is for the Xlet Manager to make decisions based on the 
platform and other environmental decisions. For example, depending on the 
amount of RAM, the Xlet Manager can decide which Xlets to move into certain 
states. Similarly, other resource considerations can be made. 


A Simple Xlet Manager 


The Personal Profile reference implementation provides an example of how a 
simple Xlet Manager could be implemented. In personal/src/share/ 
personal/classes/common/com/sun/xlet are the following source files: 


m XletManager. java — The Xlet Manager implementation. 


m XletRunner. java — The program that processes a command-line request and 
communicates this information to the Xlet Manager. 
m XletContextImpl. java — This class implements the Xlet Context interface. 


It communicates with XletManager to notify or request state changes, and 
knows what the Xlet's runtime arguments are. 


m XletStateQueue. java — This class implements a queue that keeps track of 
incoming Xlet state change requests and executes them in order. There is one 
queue per Xlet. By having this class, the caller requesting the Xlet state change 
does not have to be blocked waiting for a lock even if another Xlet state change 
request is being processed. 


m XletLifecycleHandler. java — An interface that a third party can use to 
control the Xlet lifecycle. 


The default Xlet Runner automatically initializes and starts the Xlet, but it will not 
automatically pause or destroy it. The Xlet Manager does cover the Destroy and 
Pause states and the transitions to these states. However, the Xlet needs to call 
notifyPaused or notifyDestroyed for it to enter either of these states. A more 
complicated Xlet Manager that included memory management logic, for example, 
might destroy an Xlet not in use if the system memory resources were running low 
while multiple Xlets were being run. 
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As described in Chapter 2, “Running the Sample Programs,” you run 

SimpleXletDemo with the sample Xlet Manager. The default Xlet Runner does not 
direct the Xlet Manager to call the Xlet’s pauseXlet and destroyXlet methods. 
The Xlet Manager initializes (initXlet) and starts (start Xlet) the Xlet, and the 


Xlet runs until you exit it by closing the GIK window or choosing the Destroy 
menu item. 


The Inter-Xlet Communication sample (XXCDemo) has a Main class (IXCMain) 
which talks to the Xlet Manager directly (instead of using the Xlet Runner) and 
directs the Xlet Manager to call the Xlet’s initXlet, startXlet, and 

dest royXlet methods, cycling through three of the Xlet states. 


XletRunner.java 


This sample class processes a command line to run an Xlet. It also tells the Xlet 
Manager to create, initialize, and start the Xlet, as shown in the following lines: 


XletLifecycleHandler handler = 
XletManager.createXlet (name, paths, xletArgs) ; 
handler.postInitXlet (); 

handler.postStartXlet (); 


In the preceding code, the createXlet, postInitXlet, and postStartXlet 

methods are defined in XletManager. java. (Note that they are not the same as 
the initXlet and startXlet methods on the xXlet interface, but they do cause 
these methods to be called.) 


Xlet Runner and Xlet Manager can run multiple Xlets at a time. See “Running an 
Xlet” on page 183 for information on running the Xlet Runner. 


Following is the complete XletRunner source code: 


Usage: 


+ + F F F F F F F F F 


/ 


cvm com.sun. 


A sample class to introduce xlet to the system 


xlet.XletRunner -filename <filename> 


The xlet should not be found in the classpath and 
<XletPath> is relative to the current directory. 


package com.sun.xlet; 


// To read the 
import java.io 
import java.io 
import java.io 


command line from a file. 


.BufferedReader; 
.FileReader; 
.File; 
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cvm com.sun.xlet.XletRunner -name <XletName> {-path <XletPath> | 
-codebase <URL_path>} [-args <argl> [<arg2>] [<arg3>] 


-] 
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import java.io.FileNotFoundException; 
import java.io.IOException; 
import java.util.StringTokenizer; 


// Data structure to save the command line options. 
import java.util.Vector; 


public class XletRunner { 


static String[] flags = {"-name", "-path", "-codebase", "-args", 


static boolean isKey(String s) { 
for (int i = 0; i < flags.length; i++) 
if (s.equals(flags[i])) return true; 
return false; 


public static void main(String[] args) { 
if (args.length < 2) 
printErrorAndExit (); 


// Parse the command line options. 


if (args[0].equals("-filename")) { 
String filename = args[1]; 
try { 


BufferedReader reader = new BufferedReader ( 
new FileReader (filename) ); 

Vector v = new Vector(); 

String s; 

while ((s = reader.readLine()) != null) { 


StringTokenizer tok = new StringTokenizer(s, 


while (tok.hasMoreTokens()) { 
v.addElement (tok.nextToken () ); 


} 


args = new String[v.size()]; 
for (int i = 0; i < v.size(); itt) { 
args[i] = (String) v.elementAt (i); 


} 
} catch (FileNotFoundException fnf) { 


"—filename" 


")i 


System.out.println("Could not find file " + filename) ; 


System.exit (1); 
} catch (IOException ioe) { 
System.out.printin ("IOE 
+ filename) ; 
System.exit (1); 


String name; 

String[] paths; 

String[] xletArgs = null; 

for (int i = 0; i < args.length;) { 
try { 
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xception caught while reading file 


he 


if (args[i].equals("-name")) { 
name = args[++il]; 
if (! (args[++i] .equals ("-path") | | args[i].equals("-codebase"))) { 
printErrorAndExit (); 


} 
Vector v = new Vector(); 
if (args[i].equals("-path")) { 
StringTokenizer tok = new StringTokenizer(args[+ti], 
File.pathSeparator); 
while (tok.hasMoreTokens()) { 
v.addElement (tok.nextToken ()); 
} 
} else { 
while ((i+1) < args.length && !args[it+l].equals("-args")) { 
v.addElement (args[++i]); 


} 
paths = (String[]) v.toArray(new String[v.size()]); 
if ((i + 1) < args.length && args[++i].equals("-args")) { 
v = new Vector(); 
while ((i + 1) < args.length && !isKey(args[++i])) { 
v.addElement (args[i]); 


} 
xletArgs = (String[]) v.toArray(new String[v.size()]); 


// Parsing is finished. Now start the xlet by calling methods on 
// the Xlet Manager. 


System.out.printin("@@XletRunner starting Xlet " + name); 
try { 
// Get an instance of XletLifecycle from the Xlet Manager, 
// and post a request on the handler. 
XletLifecycleHandler handler = 
XletManager.createXlet (name, paths, xletArgs) ; 
// Call a method so the xlet is initialized. 
// Xlet.initXlet (XletContext) is invoked on the Xlet Manager. 
handler.postInitXlet (); 
// Call a method so the xlet is started. 
// Xlet.startXlet() is invoked on the Xlet Manager. 
handler.postStartXlet (); 
} catch (Exception e) { 
System.out.printin("Error while loading xlet: " + name); 
e.printStackTrace(); 


} 

xletArgs = null; 
} else { 

itt; 


} catch (Exception e) { 
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e.printStackTrace()j; 
printErrorAndExit (); 


} 


// If there was a problem parsing the command line, call this method, 
// which ultimately exits. 
static void printErrorAndExit() { 


XletRunner a 
System.out.prin 
arguments"); 
System.out.prin 
class locati 
System.out.prin 
System.exit (1); 


guments from a file"); 
ln("-args <arguments separated by space> Xlet runtime 


System.out.printin("\n\nXletRunner Usage: "); 
System.out.printin("cvm com.sun.xlet.XletRunner " + 
"-name <xletname> -path <xletpath> "); 
System.out.println("\nOptions") ; 
System.out.printin("-filename <filename> Reads 
ia 


1ln("-codebase <URLs separated by space> Specifies 
n in URL format, replaces \"-path\" option"); 
in("\nRepeat arguments to run more than one xlets"); 


dt oc 


XletManager.java 


Following is the sample Xlet Manager (xletManager . java). The code includes 
comments that describe what the Xlet Manager is doing. 


The main purpose of this class is to initiate the Xlet’s state change based on the 
request coming in from the XletStateQueue and to keep track of the Xlet’s current 
state. It also loads and destroys Xlets. 


Static data is shared across all xlets. Every instance of an XletManager manages one 
Xlet. The XletManager runs a thread for every Xlet, which waits until the Xlet is 
destroyed, then performs the cleanup. The actual state change can be done either 
by posting the request through XletLifecycleHandler (which inserts the request into 
XletEventQueue), or through XletContext (which notifies the XletManager that the 
Xlet already changed its state). 


Following are some major functions of this basic Xlet Manager implementation: 


m Creates and keeps track of a class instance that implements the Xlet Context 
methods (XletContext Impl. java). Whenever an Xlet calls an XletContext 
method, it calls the implementation of the method that’s present in the 
XletContextImp1 class. 


m= Creates a Frame the first time an Xlet asks for a container. Creates a container for 
each Xlet; the container has a default size and location and is initially invisible. 
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m Keeps track of each Xlet, and it’s current state, in a hashtable. It monitors the 


lifecycle, through the manageLifecycle method, with each Xlet on a separate 
thread. The lifecycle thread is continually running. If the desiredstate value 
is not the same as the current State value, or the current State is 
Destroyed, then it breaks out of the loop. In this case, if the two values aren’t the 
same, it tries to change the Xlet state (in a switch statement) from the 
current State to the desiredstate, and starts looping again. If the 
currentState is Destroyed, it destroys the Xlet and stops the thread. 


a When first creating an Xlet, gets Xlet command-line arguments and stores them. 


a Lets another application initiate Xlet state changes, such as the Xlet Runner. 


Here is the sample code with comments: 


package com.sun.xlet; 


// Standard classes used by xlets. 


impor 


// Fo 


impor 


tf PL 
impor 
impor 
impor 
impor 
impor 
impor 
impor 
impor 
impor 
impor 
impor 
impor 


// Ut 
impor 


//For 
impor 
impor 
impor 
impor 
impor 
impor 
impor 
impor 
impor 
impor 


vides 


kee eR es aes ee eee es eee 


ava. 
ava. 
ava. 
ava. 
ava. 
-awt .MenulItem; 
ava. 
ava. 
-awt.event.ComponentAdapter; 
ava. 
ava. 
ava. 


ava 


ava 


Inter-Xlet Communication 
javax.microedition.xlet.ixc.*; 


graphic representations and event 


awt.Container; 
awt .Frame; 
awt.Insets; 
awt .MenuBar; 
awt .Menu; 


javax.microedition.xlet.*; 


(IXC) . 


awt.event.ActionEvent; 
awt.event .ActionListener; 


awt.event .ComponentEvent; 
awt.event .WindowAdapter; 
awt.event .WindowEvent; 


lity classes for saving information about xlets. 


java. 


util.Hashtable; 


loading xlets. 


ee ee ee eee ee ele 


ava. 
ava. 
-net.URLClassLoader; 
ava. 
ava. 
ava. 
ava. 
ava. 
ava. 
ava. 


ava 


io. IOException; 
net .URL; 


net .MalformedURLException; 
lang.reflect.Constructor; 
rmi.AccessException; 

security.AccessController; 
security.PrivilegedAction; 


security.Privileged 


ExceptionAction,; 


security.PrivilegedActionException; 
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support for xlets. 
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public class XletManager implements XletLifecycleHandler, ActionListener { 


// The root frame shared by all xlets 
protected static Frame theFrame; 


// The list of xlets currently managed by this Xlet Manager are stored in a 
// hashtable (specifically, the list of XletContexts). 
protected static Hashtable activeContexts = new Hashtable(); 


5] 


// The XletContext which this instance of XletManager is managing. 
private XletContextImpl context; 


5] 


// The xlet class instance. 
private Class xletClass; 


5] 


// The xlet itself. 
private Xlet xlet; 


// This xlet’s state queue. The state change request is usually posted 
// to the XletEventQueue. 
private XletStateQueue xletQueue; 


// This xlet’s thread group (Package private). 
ThreadGroup threadGroup; 


// To synchronize the state change. 

// Synchronize the existing current state and desired state with a new 
// current state or desired state during a state transition. 

private Object stateGuard = new Object (); 


// The current state of the xlet that this instance of XletManager is 

// managing. The XletManager is always trying to move the Xlet from the 

// current state to the desired state. The first state transition would be 
// from unloaded to loaded. 

private XletState currentState = XletState.UNLOADED; 


// The class specific to this reference implementation. 

// This is provided so that this implementation of XletManager 

// would work not only with the Sun Microsystems Personal Profile 
// veference implementation, but also with other Personal Profile 
// implementations. 

private static RIXletManager riXletManager = null; 


// Find out if this XletManager is running with the Sun Microsystems 
// Personal Profile reference implementation. 


static { 
try { 
Class clazz = Class.forName("com.sun.xlet.RIXletManagerImpl1") ; 
rixletManager = (RIXletManager) clazz.newInstance(); 


} catch (Exception e) {} 
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// Load the xlet class instance with a ClassLoader. 
// mainClass is the main class of the Xlet. 
// args contains the command-line arguments supplied with the arg option. 
// They will be stored in the XletContext. 
protected XletManager (ClassLoader xletClassLoader, 


[** 
* 


String mainClass, 
String[] args) throws ClassNotFoundException 


{ 


For now, confine the loading to the caller's ProtectionDomain 
final String className = mainClass; 

final ClassLoader finalClassLoader = xletClassLoader; 
try { 


xletClass = (Class) AccessController.doPrivileged ( 


new PrivilegedExceptionAction() { 


public Object run() throws ClassNotFoundException{ 
return finalClassLoader.loadClass (className) ; 


\; 


} catch (PrivilegedActionException e) { 


} 


throw (ClassNotFoundException) e.getException (); 


xx / 
xletClass = xletClassLoader.loadClass(mainClass) ; 
if (xletClass == null || (! (Xlet.class) .isAssignableFrom(xletClass) )) 


// 


throw new IllegalArgumentException ( 


"Attempt to run a non-Xlet class: " + mainClass); 


Create the XletContext for this xlet. 


context = new XletContextImpl(mainClass, args, this); 
activeContexts.put (context, this); 
this.xletClass = xletClass; 


// 
// 
// 
// 
// 
it 


If this is the first xlet that the XletManager is loading, 
then create a root Frame for all xlets. Every time a new xlet is 


added, it gets its own container inside this Frame. 


The XletManager 


sets a default size and location, adds a menu bar and window 


listener, and leaves the Frame invisible. 
(theFrame == null) { 
theFrame = new Frame("Xlet Frame"); 


theFrame.setMenuBar (new MenuBar()); 
theFrame.addWindowListener (new WindowAdapter() { 
public void windowClosing(WindowEvent e) { 
exit(); 
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public void windowIconified(WindowEvent e) { 
XletManager[] managers = 


(XletManager[]) activeContexts.values() .toArray ( 
new XletManager[activeContexts.size()]); 
for (int i = 0; i < managers.length; i++) { 


managers[i] .handleRequest (XletState.PAUSED) ; 


} 


public void windowDeiconified(WindowEvent e) { 
XletManager[] managers = 


(XletManager[]) activeContexts.values() .toArray ( 
new XletManager[activeContexts.size()]); 
for (int i = 0; i < managers.length; i++) { 


managers [i] .handleRequest (XletState.ACTIVE) ; 


} 
})3 
Menu menu = new Menu ("XletRunner"); 
MenuItem item = new MenulItem("Exit"); 
item.addActionListener (this) ; 
menu.add(item) ; 
theFrame.getMenuBar () .add(menu) ; 


// Realize the first peer with the system thread. 
theFrame.addNotify(); 


// Give the xlet 400x300 drawing space by default. 

Insets insets = theFrame.getInsets(); 

theFrame.setSize(insets.left + insets.right + 400, 
insets.top + insets.bottom + 300); 


// Tf there is more than one xlet, use FlowLayout in the Frame. 
if (activeContexts.size() > 1) { 
theFrame.setLayout (new java.awt.FlowLayout ()); 


// Set up the menu for the new xlet. 
Menu menu = new Menu(mainClass) ; 


nuIltem item = new MenulItem("Activate") ; 
tem.addActionListener (this); 

enu.add (item) ; 
tem = new Menultem("Pause") ; 
.addActionListener (this); 
enu.add (item) ; 
tem = new Menultem("Destroy") ; 
-addActionListener (this); 
-add(item) ; 
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heFrame.getMenuBar () .add(menu) ; 
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// Create a thread group that all the threads used by this xlet 

// would be a part of. This is necessary for providing a separate 

// EventQueue per xlet. 

threadGroup = new ThreadGroup (Thread.currentThread().getThreadGroup(), 
"Xlet Thread Group " + activeContexts.size()); 


// Start a lifecycle thread. 
final Thread t = new Thread(threadGroup, 
new Runnable() { 
public void run() { 
manageLifecycle(); 
} 


}, “"Xlet lifecycle for " + mainClass); 


final ClassLoader finalLoader = xletClassLoader; 
AccessController.doPrivileged(new PrivilegedAction() { 
public Object run() { 
t.setContextClassLoader (finalLoader) ; 
return null; 
} 
}); 
t.start(); 


// If an RI-specific class is here, create a separate EventQueue 

// for this xlet 

if (rixletManager != null) { 
rixletManager.createEvent Queue (threadGroup) ; 


// Create a state queue that holds this xlet’s state change requests. 
xletQueue = new XletStateQueue (this) ; 


// Now that the setup is complete, enter a request to move this xlet 
// from UNLOADED to LOADED. 
xletQueue.push (XletState.LOADED) ; 


// Return a container (a Panel) for this xlet. 
public Container getContainer() { 
Container c = new java.awt.Panel(); 
theFrame.add(c); 
theFrame.validate(); 
theFrame.setVisible (true) ; 
c.setVisible(false); 
return CF 
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// The following four methods are implementations of XletLifecycleHandler 
// methods. They allow a third party to request an xlet state change. 
// They request a state change through the xlet state queue (which holds 
// an xlet’s state change requests). 
public void postInitXlet() { 

xletQueue.push (DesiredXletState.INITIALIZE) ; 


public void postStartXlet() { 
xletQueue.push (XletState.ACTIVE) ; 


public void postPauseXlet() { 
xletQueue.push (XletState.PAUSED) ; 


public void postDestroyXlet (boolean unconditional) { 
if (!unconditional) { 
xletQueue.push (DesiredXletState.CONDITIONAL_DESTROY) ; 
} else { 
xletQueue.push (XletState.DESTROYED) ; 


// Set the state of the xlet. If the current state is destroyed, don’t 
// bother to set the state. 
public void setState(XletState state) { 

synchronized (stateGuard) { 


if (currentState == XletState.DESTROYED) 
return; 
currentState = state; 


stateGuard.notifyAl1l(); 


// Implementation of XletLifecycleHandler. Allows a third party to query 
// the xlet state. 
public int getState() { 

XletState state = getXletState(); 


if (state == XletState.LOADED) { 

return LOADED; 

else if (state == XletState.PAUSED) { 
return PAUSED; 

else if (state == XletState.ACTIVE) { 
return ACTIVE; 

else if (state == XletState.DESTROYED) { 
return DESTROYED; 

else { 
return UNKNOWN; 
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// Used internally. Returns the current XletState as an instance of 
// XletState rather than as an integer. 
public XletState getXletState() { 
synchronized (stateGuard) { 
return currentState; 


// Keeps track of whether the xlet state change request was fulfilled or not. 


boolean requestCompleted = false; 
// Typically called from XletStateQueue. 
// request. Makes sure it only performs a permissible state change. 
public void handleRequest (XletState desiredState) { 
XletState targetState = currentState; 
requestCompleted = false; 
try { 
synchronized 
af 


(stateGuard) { 

(desiredState == XletState.LOADED) { 

if (currentState != XletState.UNLOADED) 
return; 

targetState = XletState.LOADED; 

Class[] types = new Class[0]; 

Constructor m = xletClass.getConstructor (types) ; 


xlet = (Xlet) m.newInstance(new Object [0]); 
} else if (desiredState == DesiredXletState. INITIALIZE) 
if (currentState != XletState.LOADED) 
return; 
targetState = XletState.PAUSED; 
try 4 


xlet.initXlet (context) ; 


Handles xlet’s state change 


{ 


} catch (XletStateChangeException xsce) { 
targetState = XletState.DESTROYED; 
xlet.destroyXlet (true); 

} 

} else if (desiredState == XletState.ACTIVE) { 
if (currentStat !'= XletState.PAUSED) 
return; 

targetState = XletState.ACTIVE; 

ery 
xlet.startXlet(); 

} catch (XletStateChangeException xsce) { 
targetState = currentState; 

} 

} else if (desiredState == XletState.PAUSED) { 
if (currentStat !'= XletState.ACTIVE) 
return; 

targetState = XletState.PAUSED; 

xlet.pauseXlet (); 

} else if (desiredState == DesiredXletState.CONDITIONAL_DESTROY) 
if (currentState == XletState.DESTROYED) 
return; 
targetState = XletState.DESTROYED; 
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ery 
xlet.destroyXlet (false); 
} catch (XletStateChangeException xsce) { 


targetState = currentState; 
} 
} else if (desiredState == XletState.DESTROYED) { 
targetState = XletState.DESTROYED; 
if (currentState == XletState.DESTROYED) 
return; 
try { 


xlet.destroyXlet (true) ; 
} catch (XletStateChangeException xsce) {} 


} 
setState(targetState) ; 


} 


} catch (Exception e) { 


if (targetState == XletState.DESTROYED) { 
setState (XletState.DESTROYED) ; 

} else { 
handleRequest (XletState.DESTROYED) ; 


} 


requestCompleted = true; 


// Creates an xlet. This static method causes a new instance of 
// XletManager to be created, and to load the xlet. 
public static XletLifecycleHandler createXlet (String mainClass) 
throws IOException { 
return createXlet (mainClass, new String[] {"."}, null); 


public static XletLifecycleHandler createXlet (String mainClass, 
String[] paths, 
String[] args) 
throws IOException { 
java.util.Vector v = new java.util.Vector(); 
java.io.File file; 
int index = 0; 


// Converting String[] path to an array of URLs. 
for (int i = 0; i < paths.length; i++) { 
try { 
v.add(new URL(paths[i])); 
} catch (MalformedURLException mue) { 
file = new java.io.File (paths[i]); 


if (!file.exists()) { 
System.out.println("Warning: " + paths[i] + " not found"); 
} else if (file.isDirectory()) { 


v.add(new URL("file:///" + file.getCanonicalPath() + "/")); 
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} else { 
v.add(new URL("file:///" + file.getCanonicalPath())); 


} 
URLClassLoader cl = new URLClassLoader((URL[]) v.toArray (new 


URL[v.size()])); 
try { 
return (XletLifecycleHandler) new XletManager(cl, mainClass, args); 
} catch (ClassNotFoundException e) { 
e.printStackTrace(); 
throw new IOException("Cannot find class " + mainClass); 


// Really private, but invoked from inner class. 
// This thread waits for the xlet to be destroyed, then performs 


// cleanup. 
void manageLifecycle() { 
try { 
while (currentState != XletState.DESTROYED) { 


synchronized (stateGuard) { 
stateGuard.wait(); 


} 
// xlet has destroyed, do appropreate cleanup 


cleanUp (); 
} catch (Throwable t) { 
System.out.println ( 
"Xlet had unexpected exception in lifecycle thread."); 
t.printStackTrace(); 
setState (XletState.DESTROYED) ; 


// Called when the xlet is destroyed. 

private void cleanUp() { 
// First, clean up the IxcRegistry with public APIs. 
IxcRegistry regis = IxcRegistry.getRegistry (context); 
String[] list = regis.list(); 
for (int i = 0; i < list.length; i++) { 


try { 
regis.unbind(list[i]); 
} catch (AccessException ae) {; // do nothing 


} catch (Exception e) {} 


} 
if (riXletManager != null) { 
rixletManager.cleanup (context) ; 
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// Remove the Root Container from the parent frame. 

if (context.container != null) { 
theFrame.remove (context.container) ; 
context.container = null; 
theFrame.validate(); 

} 

// Clear the State Queue. 

xletQueue.destroy(); 

// remove the xlet context from the hash 

synchronized (activeContexts) { 
activeContexts.remove (context) ; 
activeContexts.notifyAll(); 


// When a user chooses a menu item from the menu bar in the root Frame, 
// process the request. 
public void actionPerformed(ActionEvent e) { 
String actionCommand = e.getActionCommand () ; 
if (actionCommand.equals("Activate")) { 
postStartXlet (); 
} else if (actionCommand.equals("Pause")) { 
postPausexXlet (); 
} else if (actionCommand.equals("Destroy")) { 
postDestroyXlet (true) ; 
} else if (actionCommand.equals("Exit")) { 
exit(); 


void exit() { 
synchronized (activeContexts) { 
XletManager[] managers = 
(XletManager[]) activeContexts.values().toArray ( 
new XletManager[activeContexts.size()]); 
for (int i = 0; i < managers.length; i++) { 
try { 
// Request for a DESTROY state to be picked up at the 
// XletStateQueue. 
managers[i].postDestroyXlet (false) ; 
activeContexts.wait(1000); // wait for 1 sec for each.. 
if (activeContexts.containsValue(managers[i])) { 
// Try to interrupt anything that the XletStateQueue is doing. 
managers [i] .xletQueue. queueThread.interrupt (); 
// Force the state to be DESTROYED. 
managers [i].setState(XletState.DESTROYED) ; 
activeContexts.wait(500); // wait for .5 sec more... 
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} catch (InterruptedException ie) { 
managers[i].setState(XletState.DESTROYED) ; 


} 
System.exit (0); 


XletContextImpl java 


This class implements the Xlet Context interface. It communicates with 
XletManager to notify or request state changes, and knows what the Xlet's 
runtime arguments are. 


package com.sun.xlet; 


// Provides graphic representations for xlets. 
import java.awt.Container; 


// Standard classes used by xlets. 
import javax.microedition.xlet.XletContext; 
import javax.microedition.xlet.XletStateChangeException; 


public class XletContextImpl implements XletContext { 


// The xlet class name. 
String mainClass; 


// Optional runtime arguments passed to this xlet from the command line. 
String[] args; 


// An instance of XletManager. It manages the xlet that 
// this XletContext belongs to. 
XletManager manager; 


// An AWT container. The xlet can draw on it. 
Container container = null; 


public XletContextImpl (String xletName, String[] args, XletManager manager) 
this.mainClass = xletName; 
this.args = args; 
this.manager = manager; 


// Returns the xlet properties, which were passed to the xlet with the 
// -args option on the command line. 
public Object getXletProperty (String key) { 
if (key == null) { 
throw new NullPointerException("Key is null"); 
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} else if (key.equals("")) { 

throw new IllegalArgumentException("Key is an empty String"); 
} else if (key.equals(ARGS)) { 

return args; 
} 


return null; 


// Returns the AWT container that the xlet is using. 


public Container getContainer() { 
if (container == null) { 
container = manager.getContainer(); 


} 


return container; 


// Request from the xlet to make itself active. startXlet is called on a 
// different thread than the one used to call resumeRequest. 
public void resumeRequest() { 

// Spawn a different thread. 

new Thread (manager.threadGroup, 

new Runnable() { 
public void run() { 
manager.handleRequest (XletState.ACTIVE) ; 


} 
}, “"ResumeRequest Thread") .start(); 
//manager.startXlet (manager) ; 


// Notification from the xlet that it is in the paused state. 
public void notifyPaused() { 
manager.setState(XletState.PAUSED) ; 


// Notification from the xlet that it is in the destroyed stat 
public void notifyDestroyed() { 
manager.setState(XletState.DESTROYED) ; 


ct 


XletStateQueue.java 


This class implements a queue that keeps track of incoming Xlet state change 
requests and executes them in order. There is one queue per Xlet. By having this 
class, the caller requesting the Xlet state change does not have to be blocked 
waiting for a lock even if another Xlet state change request is being processed. 
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package com.sun.xlet; 


public class XletStateQueue { 
EventQueueItem head = null; 
EventQueuelItem tail = null; 
XletManager manager; 


// The thread that’s processing the requests. It should be in the 


// ThreadGroup created by the XletManager. 
Thread queueThread; 


// To check if the xlet is still alive (not destroyed). 
boolean isAlive = true; 
public XletStateQueue (XletManager xletManager) { 

this.manager = xletManager; 

queueThread = new Thread(manager.threadGroup, 

new Runnable() { 
public void run() { 
while (isAlive && 


manager.getXletState() != XletStat 
dispatchEvents (); 


} 
}, “"XletStateQueue lookup thread"); 


queueThread.start (); 


// Push the request to the queue. 
public synchronized void push(XletState desired) { 
if (head == null) { 
// empty queue 
head = new EventQueuelItem (desired) ; 
tail = head; 
} else { 
tail.next = new EventQueuelItem(desired) ; 
tail = tail.next; 


} 
notifyAll(); 


// Pop the request from the queue. 
public synchronized XletState pop() { 
XletState returningState = null; 
if (head != null) { 
returningState = head.state; 
head = head.next; 


} 


return returningState; 
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// True if there is no request pending in the queue. 
public synchronized boolean isEmpty() { 
return (head == null); 


// Clear up all the requests in this queue. 
public synchronized void clear() { 
head = tail = null; 


// Destroy the queue. Called when the xlet is destroyed. 
public synchronized void destroy() { 

clear(); 

isAlive = false; 

notifyAll(); 


// Process the xlet state change request pending in this queue. 


public synchronized void dispatchEvents() { 
while (isEmpty() && isAlive) { 
try { 
wait (); 


} catch (InterruptedException e) {} 
} 
if (!isAlive) return; 
manager.handleRequest (pop ()); 


// Basic state change request date object kept in the queue. 
class EventQueuelItem { 
XletState state; 
EventQueuelItem next; 
EventQueueItem(XletState state) { 
this.state = state; 


// Extended state change request date object kept in the queue. 
// This is to hide XletState objects that cannot be of a final state 
// (INITIALIZE and CONDITIONAL_DESTROY are valid state change requests 
// but not valid states for an xlet to be in.) 
class DesiredXletState extends XletState { 

static final XletState INITIALIZE; 

static final XletState CONDITIONAL_DESTROY; 
static { 

INITIALIZE = new XletState("initialize"); 

CONDITIONAL_DESTROY = new XletState("conditional_destroy"); 
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protected DesiredXletState(String name) { 


super (name) ; 


// XletState class object - to keep track of the current xlet stat 
class XletState { 


static 
static 
static 
static 
static 


final 
final 
final 
final 
final 


XletState 
XletState 
XletState 
XletState 
XletState 
private String name = n 
protected XletState(String name) { 
this.name = 


name; 


UNLOADED; 


LOAD! 
PAUSI 


ED; 
ED; 


ACTIVE; 


DEST 
ull; 


public String toString() { 


return name; 


} 


static 
UN 


{ 
LOADED 


LOADED = 
PAUSED = 


AC 
DE 


TIVE = 


ROYED; 


new XletState ("unloaded") ; 


new XletState ("loaded") ; 
new XletState ( 
new XletState ("active"); 


STROYED = 


"paused") ; 


new XletState ("destroyed") ; 


XletLifecycleHandlerjava 


A third party can use this interface to control the Xlet lifecycle. An instance of 
XletLifecycleHandler can be obtained by calling 
XletManager.createXlet (String). 


package com.sun.xlet; 


public interface Xle 


tLifecycleHandler { 


// Define variables to keep track of the xlet states. 


public 
public 
public 
public 
public 


final 
final 
final 
final 
final 


int 
int 
int 
int 
int 


// The following 
// change to a XletManag 
public void postInitXlet (); 
public void postStartXlet (); 


LOADED = 1; 
PAUSED = 2; 
ACTIVE = 3; 
DESTROYED = 4; 
UNKNOWN = 0; 


methods allow a third party to request an xlet state 


er. 


Chapter6 Writing Xlet Managers 


93 


public void postPauseXlet (); 
public void postDestroyXlet (boolean unconditional) ; 
public int getState(); 
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CHAPTER vf 


Understanding Personal Profile 
Packages, Classes, and Interfaces 


This chapter provides a basic description of the Personal Profile packages and lists 
deprecated methods that were removed as compared to the J2SE environment: 


a “Personal Profile Packages” on page 95 
a “Running Programs Written for the J2SE Environment” on page 99 


For complete information about the Personal Profile packages, see the Javadoc and 
the Personal Profile specification. 


Personal Profile Packages 


In addition to the APIs provided by CDC and Foundation Profile, Personal Profile 
includes the following packages, many of which were modeled after standard Java 
programming packages. 


Package Description 


java.applet Classes necessary to create an applet and the 
classes an applet uses to communicate with its 
applet context. The AppletViewer class is 
included for invoking applets. In addition, the 
java.applet package provides the 
AppletContext, AppletStub, and AudioClip 
interfaces. Audio is supported by this package. 
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Package 


Description 


java.awt 


java.awt.color 


java.awt.datatransfer 


java.awt.event 


java.awt.image 


java.beans 


Classes for creating user interfaces and for 
painting graphics and images. It provides 
graphics, windowing, and input functionality. 
This package includes high-level GUI 
components, such as buttons, menus, and 
scrollbars. It also provides the general-purpose 
components, graphics, and input system on which 
lightweight GUI components can be built. There 
is no explicit support for alternative pointing 
devices, such as touch screens and styli, but these 
can be supported with MouseEvents in the AWT. 
One main difference between AWT in Personal 
Profile and the J2SE environment is that Personal 
Profile supports a subset of compositing rules 
from the J2SE environment and does not support 
Java2D. A main difference between Personal 
Profile and the PersonalJava environment is that 
Personal Profile has a few extra features such as 
compositing (although SRC_OVER can be 
approximated). 


Classes for color spaces. It contains an 
implementation of a color space based on the 
International Color Consortium (ICC) Profile 
Format Specification, Version 3.4, August 15, 1997. 
It also contains color profiles based on the ICC 
Profile Format Specification. Personal profile only 
supports the sRGB color space. sRGB is a 
proposed standard RGB color space. For more 
information, see http: //www.w3.org/pub/ 
WWW/Graphics/Color/sRGB.html. The 
abstract class serves as a color space tag to 
identify the specific color space of a Color object 
or, through a ColorModel object, of an Image, a 
BufferedImage, or a GraphicsDevice. 


Interfaces and classes for transferring data 
between and within applications. It also includes 
a clipboard class which provides a mechanism to 
transfer data using cut/copy/paste operations. 


Interfaces and classes for handling events fired by 
AWT components. It contains the classes and 
interfaces for handling events from users’ input 
devices, such as keyboards and mice, as well as 
those generated by window components, such as 
text areas, containers, and windows. 


Classes for creating and modifying images. 


Classes for JavaBean development. It contains the 
classes for runtime (as opposed to design time) 
support of JavaBeans. 


96 Personal Profile Programmer’s Guide * September 2002 


Package Description 


java.rmi Classes for Remote Method Invocation (RMI). It 


provides the fundamental interfaces for the 
programming model of the Java Remote Method 
Invocation (RMI) API. An implementation of this 
programming model is not included with this 
profile; a full implementation is provided with the 
RMI OP. The java. rmi interfaces are included 
with Personal Profile to support other 
implementations, such as the IXC mechanism of 


DVB MHP. 
java.rmi.registry Class and interfaces for the RMI registry. 
javax.microedition.xlet Interfaces used by applications and the Xlet 


Manager to communicate. It provides a means to 
invoke Java applications and Xlets that are 
written to the specification. This may require 
some command line enhancements to the CVM. 


javax.microedition.xlet.ixc Facilities for Inter-Xlet Communication (IXC). 


AWT Components 


Personal Profile supports the following AWT components: 


Button — The Button class provides a labeled button component for performing 
actions when the users clicks on the button. 

Canvas — The Canvas class provides a general purpose component for drawing 
graphics. 

Checkbox — The Checkbox class provides a checkbox GUI component for 
enabling or disabling items. 

CheckboxGroup — The CheckboxGroup class provides a mechanism for 
grouping check boxes into related groups of which only one may be enabled at a 
time. 

CheckboxMenultem — The CheckboxMenultem is a check box that appears in a 
menu. 

Choice — A Choice item is a component that appears as a popup menu of 
choices. 

Dialog — A Dialog is a popup window used to prompt interaction with the user. 
It may be either modal, or non-modal. 

FileDialog — A FileDialog is a Dialog which is used to ask the user to select a 
file. 

Frame — Personal Profile fully supports the Frame class, including support for 
multiple top level frames. 

Label — The Label class is used to place a single line of text in a container. 

List — The List component presents the user with a scrolling list of text items. 
The list can be set up so that the user can choose either one item or multiple 
items. 

Menu — The Menu class provides pull-down menu component that is 
deployable from a menu bar. 
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ms MenuBar — The MenuBar class provides a mechanism for providing a collection 
of menus which are accessible from a Frame object. 

ms Menultem — The Menultem class is the superclass of all items appearing on 
menus. A Menultem may be simply a Menultem, a CheckboxMenultem or 
another Menu. 

ms MenuShortcut — A MenuShortcut provides a means of accessing Menultems 
from the keyboard. 

a Panel — A Panel is the simple container class, providing a space in which an 
application can insert other components, including other panels. 

= PopupMenu — A PopupMenu is a Menu which "pops up" near the cursor when 
the users makes a PopupMenu gesture, such as double clicking or using a right 
mouse button. 

a Scrollbar — A Scrollbar provides a GUI component which is typically used for 
scrolling the contents of a window. 

a ScrollPane — A ScrollPane is a Container with built in scrollbars, allowing its 
contents to be scrolled when it contents are larger that can be displayed. 

a TextArea — A TextArea is a TextComponent which allows the user to edit and 
view multiple lines of text and use scrollbars as specified. 

a TextComponent — A TextComponet is the superclass of TextField and TextArea, 
providing a class for simple text display and editing. 

a TextField — A TextField is a TextComponent used for displaying and editing a 
single line of text. 

ms Window — Personal Profile fully supports the Window class, which is a top 
level window, similar to a Frame or Dialog, but without any decorations or 
Menubar. 


Optional Restrictions 


Implementations of Personal Profile can exhibit certain restrictions relative to the 
J2SE environment, as outlined in the specification. For java.awt .Graphics2D, 
only instances of AlphaComposite may be used when setting the Composite of 
the graphics context. In addition, the following packages can vary between 
implementations of Personal Profile: 


m java.awt.AlphaComposite — An implementation may approximate the 
result of the SRC_OVER rule in the case that 0.0 < As < 1.0. The Personal Profile 
reference implementation restricts the AlphaComposite behavior. It treats all 
alpha values greater that zero as opaque and alpha values of zero as transparent. 


m java.awt.Component — An implementation may prohibit setting the visible 
cursor. In such a case, calls to setCursor (java.awt.Cursor) and 
getCursor () will interact as normal, but the cursor's visible appearance need 
not change. 


m java.awt .Dialog — An implementation can optionally limit Dialog sizes, 
prohibit users from resizing Dialogs, limit Dialog locations, not support a visible 
title, or a combination of these. 


m™ java.awt.Frame — An implementation can optionally limit Frame sizes, 
prohibit users from resizing Frames, limit Frame locations, prohibit iconification, 
not support a visible title, or a combination of these. 
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m java.awt.TextField.setEchoChar — Regardless of the character selected, 
an implementation may use the astrerisk (*) as the echo character. In the 
Personal Profile reference implementaton, this behavior is restricted. 


For each optional restriction, an implementation of this Profile describes its 
behavior by means of a system property. See the specification for more information. 


Running Programs Written for the J2SE 
Environment 


With respect to APIs in the java.* packages, Personal Profile is a subset of the 
J2SE environment, version 1.3.1. Applications written to these APIs in Personal 
Profile are therefore upward-compatible to this version of the J2SE environment. 
Programs written for other versions of the J2SE environment and JDKs could also 
run on Personal Profile, sometimes without any modification to the existing code. 


The main issue you need to be aware of when you want to run programs written 
for the J2SE environment on Personal Profile is that Personal Profile doesn’t 
support Java2D or Swing. You would need to rewrite an application that used this 
functionality. 


In addition, you should remove any deprecated methods that were removed in 
Personal Profile. This section lists deprecated items, some of which were removed 
from CDC and Foundation Profile. 


Classes 

Deprecated Class Comment 

java.security.Identity This class is no longer used and has been 
deprecated. Its functionality has been replaced 
by java.security.KeyStore, the 
java.security.cert package, and 
java.security.Principal. 

java.security.IdentityScope This class is no longer used and has been 


deprecated. Its functionality has been replaced 
by java.security.KeyStore, the 
java.security.cert package, and 
java.security.Principal. 
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Deprecated Class 


Comment 


java.io.LineNumberInputStream 


java.security.Signer 


java.io.StringBufferInputStream 


This class incorrectly assumes that bytes 
adequately represent characters. As of JDK 1.1, 
the preferred way to operate on character 
streams is through the new character-stream 
classes, which include a class for counting line 
numbers. It has been removed. 


This class is no longer used and has been 
deprecated. Its functionality has been replaced 
by java.security.KeyStore, the 
java.security.cert package, and 
java.security.Principal. 


This class does not properly convert characters 
into bytes. As of JDK 1.1, the preferred way to 
create a stream from a string is through the 
StringReader class. It has been removed. 


Interface 


java.security.Certificate was deprecated. A new certificate handling 
package was created in JDK1.2. This certificate interface is entirely deprecated 
and is here to allow for a smooth transition to the new package. 


Exception 


java.lang.SecurityException was removed. 


Field 


java.lang.SecurityManager.inCheck was removed. This type of security 
checking is not recommended. It is recommended that the checkPermission call 


be used instead. 
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Methods 


The following methods were removed, unless the comments says they were 


deprecated. 


Deprecated Method 


Comment 


java.lang.ThreadGroup. 
allowThreadSuspension 
(boolean) 


java.lang.SecurityManager. 
classDepth (String) 


java.lang.SecurityManager. 
classLoaderDepth () 


java.lang.Thread. 
countStackFrames () 


java.lang.SecurityManager. 
currentClassLoader () 


java.lang.SecurityManager. 
currentLoadedClass () 


java.lang.ClassLoader. 
defineClass(byte[], int, 
int) 


java.security.SignatureSpi. 
engineGetParameter (String) 


java.security.SignatureSpi. 
engineSetParameter (String, 
Object) 


java.security.Security. 
getAlgorithmProperty (String, 
String) 


The definition of this call depends on 
ThreadGroup. suspend, which is deprecated. 
Further, the behavior of this call was never 
specified. 


This type of security checking is not 
recommended. It is recommended that the 
checkPermission call be used instead. 


This type of security checking is not 
recommended. It is recommended that the 
checkPermission call be used instead. 


The definition of this call depends on 
Thread. suspend, which is deprecated. Further, 
the results of this call were never well-defined. 


This type of security checking is not 
recommended. It is recommended that the 
checkPermission call be used instead. 


This type of security checking is not 
recommended. It is recommended that the 
checkPermission call be used instead. 


Replaced by 
defineClass(java.lang.String, byte[], 
ink; int), 


Replaced by engineSetParameter. 


This method used to return the value of a 
proprietary property in the master file of the 
"SUN" Cryptographic Service Provider in order to 
determine how to parse algorithm-specific 
parameters. Use the new provider-based and 
algorithm-independent AlgorithmParameters 
and KeyFactory engine classes (introduced in 
JDK 1.2) instead. 
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Deprecated Method 


Comment 


java.lang.String.getBytes 
(int, int, byte[], int) 


java.util.Date.getDate() 


java.util.Date.getDay () 


java.lang.System.getenv 
(String) 


java.util.Date.getHours () 


java.lang.SecurityManager. 
get InCheck () 


java.lang.Runtime. 
getLocalizedInputStream 
(InputStream) 


java.lang.Runtime. 
getLocalizedOutputStream 
(OutputStream) 


java.util.Date.getMinutes () 


java.util.Date.getMonth () 


java.security.Signature. 


getParameter (String) 


java.util.Date.getSeconds () 


This method does not properly convert characters 
into bytes. As of JDK 1.1, the preferred way to do 
this is through the getBytes (String enc) 
method, which takes a character-encoding name, 
or the get Bytes () method, which uses the 
platform's default encoding. 


As of JDK 1.1, this was replaced by 
Calendar.get (Calendar.DAY_OF_MONTH). 


As of JDK 1.1, this was replaced by 
Calendar.get (Calendar.DAY_OF_WEEK). 


The preferred way to extract system-dependent 
information is the system properties of the 
java.lang.System.getProperty methods and 
the corresponding get TypeName methods of the 
Boolean, Integer, and Long primitive types. For 


example: 
String classPath =System.getProperty 
("Java.class.path™,".") 7 


if (Boolean.getBoolean 
("myapp.exper.mode") ) 
enableExpertCommands () ; 


As of JDK 1.1, this was replaced by 
Calendar.get (Calendar.HOUR_OF_DAY). 


This type of security checking is not 
recommended. It is recommended that the 
checkPermission call be used instead. 


As of JDK 1.1, the preferred way translate a byte 
stream in the local encoding into a character 
stream in Unicode is through the 

Input StreamReader and BufferedReader 
classes. 


As of JDK 1.1, the preferred way to translate a 
Unicode character stream into a byte stream in the 
local encoding is through the 

Output StreamWriter, BufferedWriter, and 
PrintWriter classes. 


As of JDK 1.1, this was replaced by 
Calendar.get (Calendar.MINUT 


As of JDK 1.1, this was replaced by 
Calendar.get (Calendar.MONTH). 


ea 


As of JDK 1.1, this was replaced by 
Calendar.get (Calendar.SECOND). 
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Deprecated Method 


Comment 


java.util.Date. 
getTimezoneOffset () 


java.net .MulticastSocket. 
getTTL() 


java. 
getTTL() 


java.util.Date.getYear () 


java.lang.SecurityManager. 
inClass (String) 


java.lang.SecurityManager. 
inClassLoader () 


java.lang.Character. 
isJavaLetter (char) 


java.lang.Character. 
isJavaLetterOrDigit (char) 


java.lang.Character. 
isSpace (char) 


java.util.Date.parse (String) 


java.io.DataInputStream. 
readLine () 


java.io.ObjectInputStream. 
readLine () 


java.lang.Runtime. 
runFinalizersOnExit (boolean) 


net .DatagramSocketImpl. 


As of JDK 1.1, this was replaced by 
Calendar.get (Calendar.ZONE_OFFSET) and 
Calendar.get (Calendar.DST_OFFSET). 


Use the get TimeToLive method instead, which 
returns an int instead of a byte. 


Use get TimeToLive instead 


As of JDK 1.1, this was replaced by 
Calendar.get (Calendar.YEAR) —- 


1900. 


This type of security checking is not 
recommended. It is recommended that the 
checkPermission call be used instead. 


This type of security checking is not 
recommended. It is recommended that the 
checkPermission call be used instead. 


Replaced by isJavaIdentifierStart (char). 
Replaced by isJavaldentifierPart (char). 
Replaced by isWhitespace (char). 


As of JDK 1.1, this was replaced by 


DateFormat.parse(String s). 


This method does not properly convert bytes to 
characters, so it was deprecated. As of JDK 1.1, the 
preferred way to read lines of text is through the 
BufferedReader. readLine method. Programs 
that use the DataInput St ream class to read lines 
can be converted to use the BufferedReader 
class by replacing code of the form: 
DataInputStream d = new 

DataInputStream (in) ; 
with 
BufferedReader d 

= new BufferedReader (new 

Input StreamReader (in) ); 


This method does not properly convert bytes to 
characters, so it was deprecated. See 
DatalInput Stream for the details and 
alternatives. 


This method is inherently unsafe. It may result in 
finalizers being called on live objects while other 
threads are concurrently manipulating those 
objects, resulting in erratic behavior or deadlock. 
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Deprecated Method 


Comment 


java.lang.System. 
runFinalizersOnExit (boolean) 


java.util.Date.setDate (int) 


java.util.Date.setHours (int) 


java.util.Date.setMinutes 


(int) 


java.util.Date.setMonth (int) 


java.util.Date.setSeconds 
(int) 


java.net .MulticastSocket. 
setTTL (byte) 


setTTL (byte) 


java.util.Date.setYear (int) 


java.util.Date.toGMTString() 


java.util.Date. 
toLocaleString() 


java.io. 
ByteArrayOutputStream. 
toString (int) 


java.util.Date.UTC (int, int, 
int, int, int, int) 


java.net.DatagramSocketImpl. 


This method is inherently unsafe. It may result in 
finalizers being called on live objects while other 
threads are concurrently manipulating those 
objects, resulting in erratic behavior or deadlock. 


As of JDK 1.1, this was replaced by 
Calendar.set (Calendar.DAY_OF_MONTH, 
int date). 


As of JDK 1.1, this was replaced by 
Calendar.set (Calendar.HOUR_OF_DAY, int 
hours). 


As of JDK 1.1, this was replaced by 
Calendar.set(Calendar.MINUTE, int 
minutes). 


As of JDK 1.1, this was replaced by 
Calendar.set(Calendar.MONTH, int 
month). 


As of JDK 1.1, this was replaced by 
Calendar.set(Calendar.SECOND, int 
seconds). 


Use the set TimeToLive method instead, which 
uses int instead of byte as the type for ttl. 


Use set TimeToLive instead. 


As of JDK 1.1, this was replaced by 
Calendar.set (Calendar.YEAR, year + 
1900). 


As of JDK 1.1, this was replaced by 
DateFormat. format (Date date), using a 
GMT TimeZone. 


As of JDK 1.1, this was replaced by 


DateFormat.format (Date date). 


This method does not properly convert bytes into 
characters. As of JDK 1.1, the preferred way to do 
this is through the toString(String enc) 
method, which takes an encoding-name argument, 
or the toString() method, which uses the 
platform's default character encoding. 


As of JDK 1.1, this was replaced by 
Calendar.set (year + 1900, month, date, 
hrs, min, sec) or 
GregorianCalendar(year + 1900, month, 
date, hrs, min, sec), using a UTC 
TimeZone, followed by 
Calendar.getTime().getTime(). 
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Constructors 


The following constructors were removed. 


Deprecated Constructor 


Comment 


java.util.Date(int, int, 
int) 


java.util.Date(int, int, 
ant, int, int), 


java.util.Date (int, int, 
int, int, int, int) 


java.util.Date (String) 


java.net.Socket 
(InetAddress, int, 
boolean) 


java.net.Socket (String, 
int, boolean) 


java.io.StreamTokenizer 
(InputStream) 


java.lang.String (byte[], 
int) 


java.lang.String (byte[], 
rnt.idnbky dnt), 


As of JDK 1.1, this was replaced by 

Calendar.set (year + 1900, month, date) or 
GregorianCalendar(year + 1900, month, 
date). 


As of JDK 1.1, this was replaced by 

Calendar.set (year + 1900, month, date, 
hrs, min) or GregorianCalendar(year + 1900, 
month, date, hrs, min). 


As of JDK 1.1, this was replaced by 

Calendar.set (year + 1900, month, date, 
hrs, min, sec) or GregorianCalendar(year + 
1900, month, date, hrs, min, sec). 


As of JDK 1.1, this was replaced by 


DateFormat.parse(String s). 


Use DatagramSocket instead for UDP transport. 


Use DatagramSocket instead for UDP transport. 


As of JDK 1.1, the preferred way to tokenize an input 

stream is to convert it into a character stream, for 

example: 

Reader r = new BufferedReader (new 
InputStreamReader (is) ); 

StreamTokenizer st = new 
StreamTokenizer(r); 


This method does not properly convert bytes into 
characters. As of JDK 1.1, the preferred way to do this is 
through the String constructors that take a character- 
encoding name or that use the platform's default 
encoding. 


This method does not properly convert bytes into 
characters. As of JDK 1.1, the preferred way to do this is 
through the St ring constructors that take a character- 
encoding name or that use the platform's default 
encoding. 
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CHAPTER 8 


Implementing Common 
Programmatic Features 


This chapter describes how to implement various programmatic features in 
Personal Profile applications, applets and Xlets: 


a “Writing a Program That Can Be Run as an Application, Applet, and Xlet” on 
page 108 


a “Working with Frames” on page 120 

a “Creating and Using Components, Widgets, and Toolkits” on page 123 
a “Working with Color” on page 131 

a “Displaying Graphics, Images, and Animations” on page 139 

a “Working with Fonts” on page 150 

a “Working with Cursors” on page 154 

a “Publishing and Subscribing to Events” on page 162 

a “Working with Layouts” on page 167 

a “Working with Threads” on page 172 

a “Working with JavaBeans” on page 173 

Many of these tasks are similar to programming with the J2SE Platform. For 


example, some tasks that are the same between Personal Profile and the J2SE 
Platform are 


= networking 
m using native functions 
m internationalizing user interfaces 


Some tasks that you might perform in your Personal Profile programs are based on 


functionality in other software: 
a I/O reading and writing is defined in Foundation Profile. See the 


javax.microedition.io “connections framework” documentation for more 


information. 


a Setting program attributes on the command line is the same as for CVM (there 


aren’t any extra command line options). See the CVM documentation for 
information. 
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m Accessing system resources through the System class is the same as for CVM, 
and it can vary depending on the OS you're running on. See the CVM 
documentation for information. 


a RMI OP is an optional package that you can use. See the RMI OP documentation 
for more information. 


For instructions on running the samples in this chapter, see Chapter 2, “Running 


the Sample Programs.” The source code is located in personal/src/share/ 
personal/demo of the Personal Profile reference implementation. 


Writing a Program That Can Be Run as 
an Application, Applet, and Xlet 


PPDemo runs many of the samples showcased in this chapter through 
PPDemoFrame, PPDemoApplet, or PPDemoXlet. You can run all of the PPDemo 
samples at once in one window, as an application, applet, or Xlet. Or you can run 
the samples individually as applications. If you run the samples in one window, it 
can look like this: 
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Or this: 


[4 PPDemo ela 
Demos Check Boxes Dialogs Ext 


J Checkbox TextField 


Cotor 
List dem 1 
List fem z systemcot| 
List fem 3 
List tem 4 - 

List fem S 


Draw | 
List fem & 
List fem 7 image | 
List fem 0 

Font | 


List tem 9 
List nem 10 

FontMatrics 

Keyboard | 

Mouse | 

Cursor | 

Layout | 

| <- Right click here for PopUp Menu Choice ttem 1 4 Wisget | 


Note that an Xlet that is coded to run through static main as well as the Xlet 
application model can be run in the J2SE environment as long as the 

personal. jar file (which includes the microedition package) is included in 
the classpath. 


PPDemo Sample 


PPDemo is used by PPDemoFrame, PPDemoApplet, and PPDemoXlet to display 


either all of the samples, or one at a time. 


// Personal Profile packages. 


import 
import 


// For 
import 


// The 


java.awt.*; 
java.awt.event.*; 


reflection to determine what’s inside a class. 
java.lang.reflect.*; 


root class from which all event state objects are derived. 


// Used for button clicks. 


import 


java.util.EventObject; 


public class PPDemo { 
private String[] args; 
// For receiving action events (button clicks). 
private ActionListener listener; 
// The names of the samples. 
private static String[] demos = new String[] { 


"Color™; 
"SystemColor", 
"Draw", 
"Image", 
"Font", 
"FontMetrics", 
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"Keyboard", 
"Mouse", 
WCursor™, 
"Layout" 
"Widget" 

}; 


// The default layout is CardLayout. If you click a button, it displays a 
// specific card. 
CardLayout cardLayout = new CardLayout (); 
Container demoContainer = new Container (); 
String[] getDemos() { 

return demos; 


CardLayout getCardLayout() { 
return cardLayout; 

} 

Container getContainer() { 
return demoContainer; 


public PPDemo(String[] args) { 
this.args = args; 


// Create the container to hold the samples. The build method is 
// called by PPDemoFrame, PPDemoApplet, and PPDemoXlet. The Frame (which 
// holds the container) is created by one of PPDemoFrame, PPDemoApplet, 
// PPDemoXlet. 
void build(Container c) throws Exception { 

c.setBackground(new Color (0xAACCAA) ); 


// Tf you run the samples as an application: 
// ../bin/cvm PPDemoFrame 
// it displays them in one container, at the same time. 
// It creates the container to hold the samples, and then 
// instantiates the samples and adds them to the container. 
if (args.length == 0) { 

c.setSize(640, 480); 

ColorDemo color = new ColorDemo(); 


DrawDemo draw = new DrawDemo(); 

ImageDemo image = new ImageDemo() ; 

FontDemo font = new FontDemo(); 

FontMetricsDemo fontMetrics = new FontMetricsDemo(); 
KeyboardDemo keyboard = new KeyboardDemo(); 
MouseDemo mouse = new MouseDemo() ; 

CursorDemo cursor = new CursorDemo() ; 


c.setLayout (null); 
c.add(color); 
c.add(draw) ; 
c.add (image) ; 
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co 
dr 


.add(font); 
.add(fontMetrics); 
-add (keyboard) ; 
.add (mouse) ; 
-add(cursor); 


lor.setBounds(10, 24, 400, 60); 
aw.setBounds(10, 100, 400, 60); 


image.setBounds (430, 24, 200, 130); 


fo 
fo 
ke 
mo 
cu 
} else 


// 
// 
// 
// 
// 
af 


nt.setBounds(0, 170, 440, 120); 
ntMetrics.setBounds (440, 170, 200, 120); 
yboard.setBounds (10, 300, 270, 100); 
use.setBounds (290, 300, 61, 100); 
rsor.setBounds (360, 300, 270, 100); 

{ 


If you run the samples as an Xlet: 
../bin/cvm com.sun.xlet.XletRunner -name PPDemoXlet 
-path 
it displays buttons on the right, which you click to 
display each sample on the left. 
(args[0].equals("-all")) { 
// Container needs to be smaller for the Xlet. 
c.setSize(620, 460); 


// The parent container uses BorderLayout. 
c.setLayout (new BorderLayout ()); 


// One container for the buttons; one for the demo. 
// The button container uses GridLayout; 
// the demo container uses CardLayout. 


Container buttonContainer = new Container (); 
buttonContainer.setLayout (new GridLayout (demos.length, 
1, 4, 4));3 


demoContainer.setLayout (cardLayout) ; 


// Clicking a button take you to a specific card. 


listener = new ActionListener() { 
public void actionPerformed(ActionEvent e) { 
Button b = (Button) e.getSource(); 
cardLayout.show(demoContainer, b.getLabel()); 


he 


// Add one button for each demo. 

for (int i = 0; i < demos.length; i++) { 
Button b = new Button(demos[i]); 
buttonContainer.add(b); 
b.addActionListener (listener) ; 

} 

// Buttons on the right; demo on the left. 

c.add(buttonContainer, BorderLayout.EAST) ; 

c.add(demoContainer, BorderLayout.CENTER) ; 


Chapter 8 Implementing Common Programmatic Features 


111 


// Add a demo to each card. 
for (int i = 0; i < demos.length; i++) { 
String demoName = demos[i] + "Demo"; 
Class clazz = Class.forName (demoName) ; 
Component component = (Component) 
clazz.newInstance(); 
demoContainer.add(demos[i], component) ; 


// Display the last demo. 
cardLayout.show(demoContainer, demos[demos.length - 1]); 


} else { 


// Run a sample individually as an application: 
// ../bin/cvm PPDemoFrame demo 

// The individual demos use BorderLayout so that they automatically 
// scale when the frame is resized. 


c.setLayout (new BorderLayout ()); 
String demoName = args[0] + "Demo"; 
Class clazz = Class.forName (demoName) ; 
Component component = null; 
if (args.length == 1) { 
component = (Component) clazz.newInstance(); 
} else { 
// Process optional command line arguments. 
Integer[] parameters = new Integer[args.length - 1]; 
Class[] types = new Class[args.length - 1]; 
for (int i = 0; i < parameters.length; i++) { 
parameters[i] = new Integer(args[i + 1]); 
types[i] = int.class; 


} 
Constructor constructor = 
clazz.getConstructor (types) ; 
component = (Component) 
constructor.newInstance (parameters) ; 
} 
// Set the size of the window with the default size or the size 
// specified on the command line. 
Dimension d = component.getSize(); 
c.setSize(d.width + 20, d.height + 40); 
c.add(component) ; 
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Demo Sample 


All of the samples that use PPDemo extend Demo, which sets up the container, 
whether the sample is run as an application, applet, or Xlet: 


import java.awt.*; 


public class Demo extends Container { 
public Demo() { 
this (200, 100); 


public Demo(int width, int height) { 
setSize(width, height); 


public Dimension getMinimumSize() { 
return getSize(); 


public Dimension getPreferredSize() { 
return getSize(); 


public void paint(Graphics g) { 
g.setColor(Color.black) ; 
Dimension d = getSize(); 
g.drawRect (0, 0, d.width - 1, d.height - 1); 
// Need this to display buttons in layout demos. 
super.paint (g); 


PPDemoFrame Sample 


PPDemoFrame processes the command line, creates a Frame, and calls the 
PPDemo .build method. It runs all or one of the samples. 


import java.awt.*; 
import java.awt.event.*; 
import java.util.EventObject.*; 


public class PPDemoFrame extends Frame implements ActionListener { 
AboutDialog dialog; 
private ActionListener listener; 
public static void main(String[] args) throws Exception { 
if (args.length > 0) { 
if (args[0].startsWith("-h")) { 
printUsage(); 
System.exit (1); 
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if ('!args[0].equals("-all") && 
'args[0].equals("Animator") && 
'args[0].equals("Color") && 
'args[0].equals("SystemColor") && 
'args[0].equals("Draw") && 
'args[0].equals("Image") && 
'args[0].equals("Font") && 
'args[0].equals("FontMetrics") && 
'args[0].equals("Keyboard") && 
'args[0].equals ("Mouse") && 
'args[0].equals("Cursor") && 
'args[0].equals("Layout") && 
'args[0].equals("FlowLayout") && 
'args[0].equals("BorderLayout") && 
'args[0].equals("GridLayout") && 
'args[0].equals("GridBagLayout") && 
'args[0].equals("CardLayout") && 
'args[0].equals("NullLayout") && 
'args[0].equals("Widget")) { 
printUsage(); 
System.out.println("ERROR: Invalid demo: " + args[0]); 
System.out.printin(""); 
System.exit (1); 
} 
if ((args[0].startsWith ("Font") | | args[0].startsWith("FontMetrics") ) 
&& args.length > 4) { 
printUsage(); 
System.out.println("ERROR: Incorrect number of arguments"); 
System.out.printin(""); 
System.exit (1); 
} 
if ((!args[0].equals("Font") && !args[0].equals("FontMetrics")) && 
(args.length != 1 && args.length != 3)) { 
printUsage(); 
System.out.println("ERROR: Incorrect number of arguments"); 
System.out.printin(""); 
System.exit (1); 
} 
} 
Frame frame = new PPDemoFrame (args) ; 


frame.setVisible (true) ; 


static void printUsage 


( 
System.out.printin(""); 
System.out.printin("USAGE:"); 
System.out.printin(" cvm PPDemoF 
System.out.printin("") 
System.out.printin("OPTIONS:"); 
System.out.printin(" -all 
System.out.printin(" -help = Pri 
System.out.printin(""); 
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= Run all demos selectabl 


by buttons"); 
nt this help message"); 


System.out.printin("The demo argument must be one of:"); 
System.out.printin(" Color width height]"); 
System.out.printin(" SystemColor width height]"); 
System.out.printin(" Draw width height]"); 
System.out.printin(" Image [width height]"); 
System.out.printin(" Font size | width height | width height 
size]"); 
System.out.printin(" FontMetrics size | width height | width height 
size]"); 
System.out.printin(" Keyboard width height]"); 
System.out.printin(" Mouse [width height]"); 
System.out.printin(" Cursor width height]"); 
System.out.printin(" Layout [width height]"); 
System.out.printin(" FlowLayout width height]"); 
System.out.printin(" BorderLayout width height]"); 
System.out.printin(" GridLayout width height]"); 
System.out.printin(" GridBagLayout [width height]"); 
System.out.printin(" CardLayout width height]"); 
System.out.printin(" NullLayout width height]"); 
System.out.printin(" Widget [width height]"); 
System.out.printin(""); 
System.out.printin("If no options or demos are specified then"); 
System.out.printin("most of the demos are run in a single frame."); 
System.out.printin(""); 


public PPDemoFrame(String[] args) throws Exception { 


PPDemo demo = new PPDemo (args) ; 
String[] demos = demo.getDemos(); 
final Container demoContainer = demo.getContainer (); 
final CardLayout cardLayout = demo.getCardLayout (); 
demo.build(this); 
String title = "PPDemo"; 
if (args.length > 0 && !args[0].equals("-all")) { 
title = args[0]; 
for (int i= 1; i < args.length; i++) { 
title += " "+ args[il]; 


} 
setTitle (title); 
addWindowListener (new WindowAdapter() { 
public void windowClosing(WindowEvent e) { 
System.exit (0); 


i 
Toolkit toolkit = getToolkit(); 
Dimension screen = toolkit.getScreenSize(); 


Dimension dim = getSize(); 
setLocation((screen.width - dim.width) / 2, (screen.height - dim.height) 
/ 3); 
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// Creating a menu bar that demonstrates this feature as well as menu 
// checkboxes and file dialogs as heavyweight item demonstrations. 


// Method that creates the listener for the demo menu as it is clicked. 


listener = new ActionListener() { 
public void actionPerformed(ActionEvent e) { 
MenuItem d = (MenuItem) e.getSource(); 


cardLayout.show(demoContainer, d.getLabel()); 


hi 
// Creating the menu bar. 
// Prevents menu bar from showing when the -all statement is not used. 


if (args.length > 0 && args[0].equals("-all")) { 
MenuBar mb = new MenuBar(); 
Menu ml = new Menu ("Demos"); 
Menu m2 = new Menu ("Check Boxes"); 
Menu m3 = new Menu ("Dialogs"); 
Menu m4 = new Menu ("Exit"); 
// Adds the links and names to the demos to the menu bar. 
for (int i = 0; i < demos.length; i++) { 
MenuItem d = new MenulItem(demos[i]); 
ml.add(d); 


d.addActionListener (listener); 

} 

MenuItem fileMenuItem = new MenulItem ("File dialog..."); 

fileMenulItem.addActionListener (this) ; 

// Creates a new exit item on the menu, also implements the 

// ActionListener within this method to provide the exit feature. 

// Utilizes CTRL+E to exit. 

MenuShortcut msl = new MenuShortcut (KeyEvent.VK_E); 

MenulItem exitMenuItem = new MenulItem ("Exit Demos", msl); 

exitMenulItem.addActionListener(new ActionListener() { 
public void actionPerformed(ActionEvent ae) { 

System.exit (0); 


3 
//Provides the dialog menu item. 
MenuItem dialogMenuItem = new MenuItem ("Dialog "); 
dialogMenulItem.addActionListener(new ActionListener() { 
public void actionPerformed(ActionEvent ae) { 
dialog = new AboutDialog (PPDemoFrame.this, "Dialog", true); 
dialog.setLocation(600, 400); 
dialog.setVisible (true); 


m2.add(new CheckboxMenuItem ("Checkbox Menu item 1")); 
m2.add(new CheckboxMenuItem ("Checkbox Menu item 2")); 
m3.add(dialogMenulItem) ; 

m3.add(fileMenulItem) ; 

m4.add(exitMenultem) ; 
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a 


mb.add(m1); 
mb.add(m2) ; 
mb.add (m3) 
mb.add (m4); 
setMenuBar (mb) ; 


, 


public void actionPerformed(ActionEvent e) { 


if (e.getActionCommand().equals("Close ")) { 
System.exit (0); 
} else { 


FileDialog fd = new FileDialog(this, "FileDialog"); 
fd.setVisible (true) ; 


} 
public class AboutDialog extends Dialog { 
AboutDialog(Frame dw, String title, boolean modal) { 
super(dw, title, modal); 
//Create middle section. 
Panel pl = new Panel(); 
Label label = new Label("This is a dialog"); 
pl.add(label); 
add("Center", pl); 
// Create bottom row. 
Panel p2 = new Panel(); 
p2.setLayout (new FlowLayout (FlowLayout.RIGHT) ); 
Button b = new Button("Close"); 
b.addActionListener(new ActionListener () { 
public void actionPerformed(ActionEvent ae) { 


AboutDialog.this.dispose(); 


i 

p2.add(b); 

add("South", p2); 

//Initialize this dialog to its preferred size. 
pack (); 


PPDemoApplet Sample 


PPDemoApplet is an applet that displays a demo with a click of a button. See 


Chapter 4, “Writing Applets,” for more information on applets. 


import java.applet.*; 
import java.awt.*; 
import java.awt.event.*; 
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public class PPDemoApplet extends Applet { 
private PPDemo demo; 
private Container container; 
public static void main(String[] args) throws Exception { 


System.out.printin(""); 

System.out.printin("USAGE:"); 

System.out.printin(" cvm sun.applet.AppletViewer PPDemoApplet.html") ; 
System.out.printin(""); 


System.exit (1); 


public void init() { 
System.out.printin("The applet has been initialized. "); 
try { 
container = new Container (); 


// Initialize each demo. 
demo.build(this) ; 

} catch (Exception e) { 
e.printStackTrace(); 


public PPDemoApplet() { 
String[] args = new String[] {"-all"}; 
demo = new PPDemo (args) ; 


public void start() { 
System.out.printin("The applet has started. "); 
container.validate(); 
container.setVisible (true); 
//Set the demo to display on startup. 
demo.getCardLayout () .show(demo.getContainer(), demo.demos[0]); 


public void stop() {} 


public void destroy() {} 


PPDemoXlet Sample 


PPDemoxX{let is an Xlet that displays a demo with a click of a button. See Chapter 5, 
“Writing Xlets,” for more information on Xlets. 


import java.awt.*; 
import java.awt.event.*; 
import javax.microedition.xlet.*; 
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public class PPDemoXlet implements Xlet { 


private XletContext context; 
private Container container; 
private PPDemo demo; 

private ActionListener listener; 


public static void main(String[] args) throws Exception { 


System.out.printin(""); 

System.out.printin("USAGE:"); 

System.out.printin(" cvm com.sun.xlet.XletRunner -nam 
PPDemoXlet -path ."); 

System.out.printin(""); 


System.exit (1); 


public PPDemoXlet() { 
String[] args = new String[] {"-all"}; 
demo = new PPDemo (args) ; 


// Initialize the Xlet. Get the container from the Xlet Manager 
// and call PPDemo.build, passing in the container. The container 
// is invisible. 
public void initXlet (XletContext context) { 

log("initXlet called"); 


this.context = context; 

try { 
// Get the container from the XletContext. 
container = context.getContainer(); 


// Initialize each demo that is added to the container. 
demo.build(container) ; 
// Set the demo to display on startup. 
demo.getCardLayout () .show(demo.getContainer(), 
demo.demos[0]); 
// Set the size. 
container.setSize (400, 300); 
container.validate(); 
} catch (Exception e) { 
e.printStackTrace(); 


// Start the Xlet. Make the container visible. 
public void startXlet() { 
log("startXlet called"); 
container.setVisible (true) ; 


// Pause the Xlet. Could make it invisible. 
public void pauseXlet() { 
log("pauseXlet called"); 
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// Destroy the Xlet. Could perform cleanup. 
public void destroyXlet (boolean unconditional) { 


} 


log("destroyXlet called"); 


// Method to output the state of the Xlet. 
void log(String s) { 


} 


import 
import 
import 


public 


System.out.printin("PPDemoXlet: " + s); 


Working with Frames 


The FrameDemo sample illustrates the differences between the J2SE Platform and 
Personal Profile by providing six buttons: 


New — creates a new Frame 

Title — adds a * to the current title of the frame. 

Size — changes the frame to a random size 

Resizable — toggles the resizable property of the frame (the button color is red 
when you can’t resize) 

a Location — moves the frame to a random location 

m State — toggles the frame state between NORMAL and ICONIFIED 


You can run FrameDemo in a Personal Profile, Personal Basis Profile, or J2SE 
environment. If a Personal Profile implementation doesn’t support any of these 
behaviors, clicking the button will have no effect. The Personal Profile reference 
implementation supports all of these behaviors. See “Optional Restrictions” on 
page 98 for more information on Frame behavior in Personal Profile. 


When you run it, the sample looks like this in the Personal Profile reference 
implementation: 


Following is the code for FrameDemo.java: 


java.awt.*; 
java.awt.event.*; 
java.util.EventObject; 


class FrameDemo extends Frame { 


static int count; 
static int number; 
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public static void main(String[] args) throws Exception { 
Frame frame = new FrameDemo() ; 
frame.setVisible (true) ; 


public FrameDemo() { 
count++; 
number++; 
setTitle("" + count); 


setSize(200, 200); 

setLocation(100, 100); 

addWindowListener (new WindowAdapter() { 

public void windowClosing(WindowEvent e) { 
FrameDemo.this.setVisible (false); 
FrameDemo.this.dispose(); 
number--; 
if (number == 0) { 
System.exit (0); 


})3 

// Add the buttons. 

setLayout (new GridLayout (3, 2)); 

DemoButton newButton = new DemoButton ("New") ; 

DemoButton titleButton = new DemoButton ("Title"); 
DemoButton sizeButton = new DemoButton ("Size"); 
DemoButton resizableButton = new DemoButton("Resizable"); 
DemoButton locationButton = new DemoButton ("Location") ; 
DemoButton stateButton = new DemoButton ("State") ; 


// Create a new Frame when New is clicked. This behavior was restricted 


// in Personal Basis Profile, but not in Personal Profile. 
newButton.addMouseListener (new MouseAdapter() { 
public void mouseClicked(MouseEvent e) { 
Frame frame = new FrameDemo(); 
Toolkit toolkit = getToolkit(); 
Dimension d = toolkit.getScreenSize()j; 
frame.setLocation((int) (Math.random() * 2 * d.width 
/ 3), (int) (Math.random() * 2 * d.height / 3)); 

frame.setVisible (true) ; 


})e 


// Add a * to the title when Title is clicked. A Personal Profile 
// implementation may not support a visible title on Frames. 
titleButton.addMouseListener (new MouseAdapter() { 
public void mouseClicked(MouseEvent e) { 
setTitle(getTitle() + "*"); 


})e 
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// Resize the Frame when Size is clicked and the Frame is resizable. A 
// Personal Profile implementation may support one Frame size only. 
sizeButton.addMouseListener (new MouseAdapter() { 
public void mouseClicked(MouseEvent e) { 
if (!isResizable()) { 
return; 


} 
Toolkit toolkit = getToolkit(); 

Dimension d = toolkit.getScreenSize(); 
setSize((int) (Math.random() * d.width / 2) + 60, 
(int) (Math.random() * d.height / 2) + 60); 

validate (); 


})F 


// Toggle whether a Frame is resizable when Resizable is clicked. A Personal 
// Profile implementation may prohibit a user from resizing Frames. 
resizableButton.addMouseListener (new MouseAdapter() { 

public void mouseClicked(MouseEvent e) { 
if (isResizable()) { 
setResizable (false); 


((DemoButton) e.getSource()).setForeground(Color.red); 
} else { 

setResizable (true); 

DemoButton tmpDemoButton = (DemoButton) e.getSource(); 


tmpDemoButton.setForeground (tmpDemoButton.DEFAULT_COLOR) ; 


})F 


// Change the Frame size when Location is clicked. A Personal Profile 
// implementation may support one Frame location only. 
locationButton.addMouseListener (new MouseAdapter() { 
public void mouseClicked(MouseEvent e) { 
Toolkit toolkit = getToolkit (); 
Dimension d = toolkit.getScreenSize(); 
setLocation((int) (Math.random() * 2 * d.width / 3), 
(int) (Math.random() * 2 * d.height / 3)); 


})F 


// Iconify the Frame when State is clicked. A Personal Profile 
// implementation may prohibit iconification. 
stateButton.addMouseListener (new MouseAdapter() { 
public void mouseClicked(MouseEvent e) { 
setState(getState() == NORMAL ? ICONIFIED : NORMAL); 


})e 


add 
add 
add 
add 


newButton) ; 
titleButton); 
sizeButton); 
resizableButton); 
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add(locationButton) ; 
add(stateButton) ; 


Creating and Using Components, 
Widgets, and Toolkits 


Personal Profile supports lightweight and heavyweight components. It includes 
java.awt.Component, Container, Window, and Frame; as well as the other 
AWT components, such as a button, checkbox, container, label, list, text area or 
field, and scrollbar. If you need other components, you can create your own and 
optionally adhere to existing standards, such as HAVi or DVB MHP. Personal 
Profile includes the java.awt.Polygon, Rectangle, and Point classes, which 
you can optionally use as the basis for creating your own components. All custom 
components must extend the Component class. 


Working with AWT Components 


The Widget sample uses some common Personal Profile AWT components, 
including 

m TextArea 

a TextField 
a Label 
= Button 
m Checkbox 
a Choice 
a List 

a PopupMenu 
a Menultem 

= MenuShortcut 
m Panel 
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When you run it, the sample looks like this in the Personal Profile reference 


implementation: 
(a 1) 
Button Checkbox TextField 


fSfusritent 


List tem 10 


— <= 


| <= Right click here for PopUp Menu = Choice tem | | 


Whenever you use a component, a message appears in the left text area. 


In addition, PPFrameDemo demonstrates the following components: 


MenuBar 

Menu 

Menultem 
CheckboxMenultem 
MenuShortcut 
Panel 

Dialog 

Label 

Button 


See “PPDemoFrame Sample” on page 113 for more information. 


Following is WidgetDemo.java: 


import java.awt.*; 
import java.awt.event.*; 


class WidgetDemo extends Demo implements ActionListener, ItemListener { 
TextArea tArea; 

Button b; 

TextField f; 

Checkbox ck; 

Choice c; 

List 1; 

public WidgetDemo() { 
this (400, 400); 


public WidgetDemo(int width, int height) { 
super (width, height); 
build(); 
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public void build() { 


// Add three panels that will be arranged using BorderLayout. 
Panel topPanel = new Panel(); 

MyPanel bottomPanel = new MyPanel(); 

Panel centerPanel = new Panel(); 

setLayout (new BorderLayout ()); 


tArea = new TextArea("TextArea", 5, 15); 


// Add small things (button, text field, checkbox) to the top panel. 
// Arrange them using GridLayout. Register each component to receive 
// action events. 

b = new Button("Button"); 

£ new TextField("TextField", 15); 

ck = new Checkbox ("Checkbox") ; 

b.addActionListener (this); 

f.addActionListener (this); 

ck.addItemListener (this) ; 

topPanel.setLayout (new GridLayout (1, 3)); 

topPanel.add(b) ; 

topPanel.add(ck) ; 

topPanel.add(f); 


// The center panel uses GridLayout. 
centerPanel.setLayout (new GridLayout(1l, 2)); 


// Add big things (text area and list) to the center panel. Arrange them 
// in a panel using BorderLayout, text area on the left and list on the 
// vight. Register each component to receive action events. 
Panel p = new Panel(); 
p.setLayout (new BorderLayout ()); 
p.add("Center", tArea) ; 
//Put a list on the right side. 
1 = new List(3, false); 
for (int i = 1; i <= 10; itt) { 
l.add("List item " + i); 


} 

1l.addActionListener (this); 
1l.addItemListener (this); 
p.add("East", 1); 
centerPanel.add(p); 


// Add a label and popup menu to the bottom panel. 

bottomPanel.add(new Label ("<- Right click here for PopUp Menu ", 
Label.CENTER) ); 

c = new Choice(); 

c.addItemListener (this); 

c.add("Choice Item 1"); 

c 

c 


-add("Choice Item 2"); 
-add("Choice Item 3"); 
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bottomPanel.add(c); 


// Arrange the panels in the window using BorderLayout. 
add("South", bottomPanel) ; 

add("North", topPanel); 

add("Center", centerPanel); 


// Method to pick up action events and react accordingly to each of the 
// specified actions: a message is added to the text area. 
public void actionPerformed(ActionEvent evt) { 
if (evt.getSource() == b) { 
tArea.append("\nThe Button was clicked."); 


if (evt.getSource() == f) { 
tArea.append("\nThe TextField was changed to: " + f.getText()); 
if (evt.getSource() == 1) { 


tArea.append("\nA list item was selected."); 


if (evt.getActionCommand().equals("Close")) { 
System.exit (0); 


// Method to pick up list item events and react accordingly to each of the 
// specified actions: a message is added to the text area. 
public void itemStateChanged(ItemEvent e) { 
if (e.getSource() == 1) { 
Integer num = (Integer) -getItem(); 
int num2 = num.intValue(); 
tArea.append("\n" + 1l.getItem(num2) + " was selected."); 


} 


if (e.getSource() == ck) { 
if ((ck.getState()) == true) { 
tArea.append("\nThe Checkbox is selected"); 
} else { 


tArea.append("\nThe Checkbox is deselected") ; 


if (e.getSource() == c) 
tArea.append("\n" + e.getItem() + " was selected."); 


} 
// Create inner class to add popup menu. 
class MyPanel extends Panel implements ActionListener { 
PopupMenu pm = new PopupMenu ("Numbers") ; 
MyPanel() { 
pm.add(new MenuItem("One", new MenuShortcut (KeyEvent.VK_O))); 
pm.add("Two") ; 
pm.add("Three") ; 
pm.add("-"); 
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pm.add("Four") ; 

pm.add("Five"); 

// Enable mouse events and listen for action events. 
pm.addActionListener (this) ; 

add (pm) ; 

enableEvents (AWTEvent .MOUSE_EVENT_MASK AWTEvent .KEY_EVENT_MASKR) ; 


// Process popup menu event. 
protected void processMouseEvent (MouseEvent e) { 
if (e.isPopupTrigger()) { 
pm.show(this, 0, 0); 


} 


super.processMouseEvent (e) ; 


public void actionPerformed(ActionEvent evt) { 
if (evt.getSource() == pm) { 
tArea.append("\nYou have selected " + evt.getActionCommand() + 
"from the PopupMenu."); 


} 
if (evt.getActionCommand().equals("Close")) { 
System.exit (0); 


Creating a Lightweight Component 


The DemoButton sample illustrates how to create a simple, lightweight, AWT 
component that runs with Personal Profile and has its own event types. When you 
click a mouse button, the color of the button changes. The button is used in the 
FrameDemo and Layout samples. See “Working with Frames” on page 120 and 
“Working with Layouts” on page 167. 


Lightweight components need to override the getPreferredSize, 
getMinimumSize, and getMaximumSize methods, as shown in the following 
DemoButton.java code: 


public Dimension getPreferredSize() { 
return getSize(); 


public Dimension getMinimumSize() { 
return getSize(); 


public Dimension getMaximumSize() { 
return new Dimension (Integer.MAX_VALUE, Integer.MAX_VALUE) ; 
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The button has a fixed height of 20 pixels, and the width is determined by the 
length of the label: 


int w = fm.stringWidth (label); 
int h = fm.getHeight (); 
g.drawString(label, (d.width - w) / 2, h + (d.height - h) / 2 - 3); 


Lightweight components also need to override the paint method to display the 


component: 
public void paint(Graphics g) { 
Dimension d = getSize(); 
Color unselectedColor = getForeground() ; 
boolean buttonNotSelected = !pressed || !inside; 


// Draw the whole button darker. 
g.setColor(unselectedColor.darker()); 
g.fillRoundRect (0, 0, d.width, d.height, 10, 10); 


// Now draw a lighter inside if we are not selected. 

if (buttonNotSelected) g.setColor(unselectedColor) ; 

int border = 3; 

g.fillRoundRect (border, border, d.width - 2 * border, d.height —- 
2. * border, .10, 10) 4 


// Now inverse again for our font color. 

g.setColor (buttonNotSelected ? unselectedColor.darker () 
unselectedColor); 

g.setFont (DEFAULT_FONT) ; 

FontMetrics fm = g.getFontMetrics (DEFAULT_FONT) ; 

int w = fm.stringWidth (label); 

int h = fm.getHeight (); 

g.drawString(label, (d.width - w) / 2, h + (d.height - h) / 2 - 
3); 


In this case, the colors are darker when selected and lighter when deselected, and 
the buttons are drawn using round rectangles to illustrate that unlike heavyweight 
components, lightweight components do not need to be rectangular — they could 
be oval or any other shape you choose. 


To process events, the lightweight component needs either to provide a listener 
interface or to override the event processing method. In this case, it overrides the 
processMouseEvent method: 


protected void processMouseEvent (MouseEvent e) { 


switch (e.getID()) { 
case MouseEvent .MOUSE_CLICKED: 
break; 


case MouseEvent .MOUSE_ENTERED: 
inside = true; 
repaint (); 
break; 
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import 
import 
import 
import 


public 


case Mouse 
inside 
repain 
break; 


case Mouse 
presse 
repain 
break; 


case Mouse 
presse 
repain 
af (Cha 
break; 
} 


super.proc 


Event .MOUSE_EXITED: 
= false; 
t(); 


Event .MOUSE_PRESSED: 
d = true; 
t(); 


Event .MOUSE_RELEASED: 


d = false; 
t(); 
nside) return; 


essMouseEvent (e) ; 


Following is DemoBut ton. java. For more information on events, see “Publishing 
and Subscribing to Events” on page 162. 


java.awt.*; 


java.awt.event.*; 


java.util.A 


rrayList; 


java.util.EventObject; 


class DemoButton extends Component { 


private static 
private static 
private String 


Font font = new Font("sanserif", Font.PLAIN, 12); 
Color color = new Color (0xAAAACC) ; 


label; 


private boolean pressed; 


private 


boolean inside; 


public DemoButton(String label) { 


this.label 
setSize(12 


MouseEvent .MOUSE_EXITED | 


= label; 


+ 8 * label.length(), 20); 
setForeground (DEFAULT_COLOR) ; 
enableEvents (MouseEvent .MOUSE_CLICKED 

MouseEvent .MOUSE_ENTERED | 


MouseEvent .MOUSE_PRESSED | 
MouseEvent .MOUSE_RELEASED 


public String getLabel() { 
return label; 


public Dimension getPreferredSize() { 
return getSize(); 
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public Dimension getMinimumSize() { 
return getSize(); 


public Dimension getMaximumSize() { 
return new Dimension (Integer.MAX_VALUE, Integer.MAX_VALUE) ; 


public void paint(Graphics g) { 
Dimension d = getSize(); 
Color unselectedColor = getForeground() ; 
boolean buttonNotSelected = !pressed || !inside; 


// Draw the whole button darker. 
g.setColor(unselectedColor.darker()); 
g.fillRoundRect (0, 0, d.width, d.height, 10, 10); 


// Now draw a lighter inside if we are not selected. 

if (buttonNotSelected) g.setColor(unselectedColor) ; 

int border = 3; 

g.fillRoundRect (border, border, d.width - 2 * border, d.height - 
2 * border, 10, 10); 


// Now inverse again for our font color. 

g.setColor (buttonNotSelected ? unselectedColor.darker () 
unselectedColor); 

g.setFont (DEFAULT_FONT) ; 

FontMetrics fm = g.getFontMetrics (DEFAULT_FONT) ; 

int w = fm.stringWidth (label); 

int h = fm.getHeight (); 

g.drawString(label, (d.width - w) / 2, h + (d.height - h) / 2 - 
3); 


protected void processMouseEvent (MouseEvent e) { 


switch (e.getID()) { 
case MouseEvent .MOUSE_CLICKED: 
break; 


case MouseEvent .MOUSE_ENTERED: 
inside = true; 
repaint (); 
break; 


case MouseEvent .MOUSE_EXITED: 
inside = false; 
repaint (); 
break; 
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case MouseEvent .MOUSE_PRESSED: 
pressed = true; 
repaint (); 
break; 


case MouseEvent .MOUSE_RELEASED: 
pressed = false; 


repaint (); 
if (!inside) return; 
break; 

} 

super.processMouseEvent (e) ; 


Working with Color 


Personal Profile provides java.awt .Color, SystemColor, and 
AlphaComposite classes so you can work with colors. 


Personal Profile supports three Porter-Duff rules: 


m The CLEAR rule will ignore both the color and the alpha values for the 
destination and source, and set the color and alpha values to 0, which is black 
with no transparency. 


a The SRC rule will ignore the destination color and alpha values and simply use 
whatever is specified in the source color and alpha values. 


The SRC_OVER rule will composite (blend) the destination and source color and 
alpha values. This is subject to a possible restriction: if the system property 
java.awt.AlphaComposite.SRC_OVER.isRestricted is true, then it is 
restricted, possibly meaning that the underlying platform does not support 
alphablending. Personal Profile doesn’t require that platforms support full 
alphablending, so when you use it, the results can vary from platform to platform. 
Note that the Personal Profile reference implementation doesn’t support 
alphablending, but another implementation might. 


Color Sample 


This sample creates five arrays of colors and displays those colors. From top to 
bottom, the sample shows: 


1. A range of RGB color values. 


An array of colors that vary the Red, Green and Blue components, starting with 
red, moving to green, then to blue and then back to red again. 


Chapter 8 Implementing Common Programmatic Features 131 


2. Grayscale color values. 


An array of colors where the red, green and blue components are all the same, 
specifically, ranging from black to white with all grey values in between. 


3. Standard color values. 


An array containing all the public static final Color fields in the Color class, 
such as Color.red, Color.lightGray, and so on. 


4, The effect of the darker and lighter methods of the Color class. 


An array of red, green, blue and grey colors, each one having the darker and 
lighter methods called on it. 


5. Alphablending with colors. 


An array of red, green, blue, black, grey and white colors, each constructed with 11 
different alpha values ranging from 0.0f, 0.1f, 0.2f ... to 1.0f 


The sample looks like this: 


| Color (e/a) 


The static initializer creates all the color arrays: 


static { 


The paint method draws black horizontal lines, 4 pixels apart, across the whole 
sample so that the effect of the alpha-blending colors can be seen: 


public void paint (Graphics g) { 
Dimension d = getSize(); 
g.setColor(Color.black) ; 
for (int y = 2; y < d.height; y t= 4) { 
g.drawLine(0, y, d.width, y); 
} 
draw(rgb, 0); 
draw(bw, 1); 
draw(colors, 2); 
draw(shades, 3); 
draw(alphas, 4); 


Then each array of colors is displayed using the draw method: 
private void draw(Color[] array, int offset) { 
Graphics g = getGraphics(); 
Dimension d = getSize(); 
int h = d.height / 5; 
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int x = 0; 
int y = offset * h; 
if (d.width < array.length) { 
for (x = 0; x < d.width; x++) { 
int index = x * array.length / d.width; 
g.setColor (array [index]); 
g.drawLine(x, y, x, y + h); 
} 
} else { 
int w d.width / array.length; 
int r = d.width % array.length; 
for (int i = 0; i < array.length; i++) { 
int fill = r-->0?71: 0; 
g.setColor(array[i]); 
g.fillRect(x, y, w + fill, h); 
x += wit fill; 


} 


Following is the complete ColorDemo.java code: 


import java.awt.*; 


class ColorDemo extends Demo { 
private static Color[] rgb; 
private static Color[] bw; 
private static Color[] colors; 
private static Color[] shades; 
private static Color[] alphas; 


public ColorDemo() { 
this(400, 300); 


public ColorDemo(int width, int height) { 
super (width, height); 


public void paint(Graphics g) { 
Dimension d = getSize(); 
g.setColor(Color.black); 
for (int y = 2; y < d.height; y t= 4) { 

g.drawLine(0, y, d.width, y); 

} 
draw(rgb, 0); 
draw(bw, 1); 
draw(colors, 2); 
draw(shades, 3); 
draw(alphas, 4); 
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private void draw(Color[] array, int offset) { 


Graphics g = getGraphics(); 
Dimension d = getSize(); 
int h = d.height / 5; 
int x = 0; 
int y = offset * h; 
if (d.width < array.length) { 
for (x = 0; x < d.width; x++) { 


int index = x * array.length / d.width; 


g.setColor (array [index]); 
g.drawLine(x, y, xX, y + h); 
} 
} else { 
int w 


d.width / array.length; 
int r = d.width % array.length; 


for (int i = 0; i < array.length; i++) { 


int fill =r-->0?1: 0; 
g.setColor(array[i]); 
g.fillRect(x, y, w + fill, 
x += w+ fill; 


static { 
// A range of RGB color values. 
rgb = new Color[1000]; 
int[] array = new int[rgb.length]; 
int sixth = rgb.length / 6; 
for (int i = 0; i < array.length; i 
if (i <= 2 * sixth) { 
array[i = 0; 
} else if (i > 2 * sixth && i < 
array[i] = (i - 2 * sixth) 
} else if (i 
] = 255; 
} else if (i > 5 * sixth && i < 
array[i] 
} else if (i 


i 
( 
i 
( 

array[i 
( 
i 
(i >= 6 * sixth) { 
i] = 0; 


array 


h); 


++) { 


3 * sixthy { 
* 255 / sixth; 


>= 3 * sixth && i <= 5 * sixth) { 


6 * sixth) { 


255 -— (1-5 * sixth). * 255 /. sixth; 


for (int i = 0; i < rgb.length; i++) { 


int r = array[(i + 4 * sixth) % 
int g array[(i + 2 * sixth) % 
int b = array[i]; 

rgb[i] = new Color(r, g, b); 
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rgb.length]; 
rgb.length]; 


// Grayscale color values 


bw = new Color[1000]; 

for (int i = 0; i < bw.length; itt) { 
int x = i * 255 / bw.length; 
bw[i] = new Color(x, x, x); 


} 

// Standard color values 

colors = new Color[] { 
Color.red, 
Color.green, 
Color.blue, 
Color.cyan, 
Color.magenta, 
Color.yellow, 
Color.orange, 
Color.pink, 
Color.black, 
Color.darkGray, 
Color.gray, 
Color.lightGray, 
Color.white 


}; 


// The effect of the darker and lighter methods of the 


// Color class 

shades = new Color[] { 
new 
new 
new 
new 
new 
new 
new 
new 
new 
new 
new 
new 


Color (0xAA0000), 
Color (0xAA0000) .brig 


Color (0x00AA00), 
Color (0x00AA00) .brig 


Color (0x0000AA), 
Color (0x0000AA) .brig 


Color (OxAAAAAA), 

Color (OxAAAAAA) .brig 

}; 

// Alphablending with colors 

alphas = new Color[] { 
new Color(1.0f, 0. 


new Color(1.0f, 0O.Of, O. 


Color (0xAA0000) .darker(), 


hter(), 


Color (0x0O0AA00) .darker(), 


hter(), 


Color (O0xO0000AA) .darker(), 


hter(), 


Color (OxAAAAAA) .darker(), 


hter () 


new Color(1.0£, L.Of, 2.0£, 1.08) 


}; 
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SystemColor Sample 


The SystemColor sample displays the standard system colors contained in the 
SystemColor class: 


SystemColor 


[0 m 
[192,192,192] activeCapt 
[255,255,255] activeCapt 


[192,192,192] anactaveCaptaonBorder 
192,192,192] anactaveCaptionTent 


It creates an array of all the public static final SystemColor fields in the 
SystemColor class: 


colors = new Color[] { 
SystemColor.activeCaption, 
SystemColor.activeCaptionBorder, 
SystemColor.activeCaptionText, 


It also creates an array of strings containing the RGB values of the corresponding 
colors and their names: 


strings = new String[] { 
"activeCaption", 
"activeCaptionBorder", 
"activeCaptionText", 


for (int i = 0; i < strings.length; i++) { 


int[] rgb = new int[3]; 

rgb[0] = colors[i].getRed(); 
rgb[1] = colors[i].getGreen (); 
rgb[2] = colors[i].getBlue(); 


The paint method displays the strings over rectangles filled with those system 
colors: 


for (int i = 0; i < colors.length; i++) { 
Color color = colors[il; 
g.setColor(color) ; 
g.fillRect(x, y, w, h); 
int brightness = 0; 
brightness += color.getRed(); 
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brightness += color.getGreen(); 

brightness += color.getBlue(); 

if (brightness < 360) { 
g.setColor(Color.white) ; 

} else { 
g.setColor(Color.black); 

} 

g.drawString(strings[i], 4, y + 8 * h / 10); 

y += h; 

} 


Following is the complete SystemColorjava code: 


import java.awt.*; 


class SystemColorDemo extends Demo { 
private static Color[] colors; 
private static String[] strings; 


public SystemColorDemo() { 
this (300, 300); 


public SystemColorDemo(int width, int height) { 
super (width, height); 


public void paint(Graphics g) { 
Dimension d = getSize(); 
int w = 3 * d.width / 35 / 2 - 2; 
int h = d.height / colors.length - 2; 
int fontSize =w<h ?w: h; 
Font font = new Font ("Monospaced", Font.PLAIN, fontSize); 


int x = 0; 
int y = 0; 
Ww d.width - 1; 


h = d.height / colors.length; 
g.setFont (font); 
for (int i = 0; i < colors.length; i++) { 
Color color = colors[i]; 
g.setColor (color); 
g.fillRect (x, y, w, h); 
int brightness = 0; 
brightness += color.getRed(); 
brightness += color.getGreen(); 
brightness += color.getBlue(); 
if (brightness < 360) { 
g.setColor(Color.white) ; 
} else { 
g.setColor(Color.black) ; 
} 
g.drawString(strings[i], 4, y + 8 * h / 10); 
y += h; 
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static { 


colors 


}; 


Sys 
Sys 


Sys 


strings 


for 


“ac 
“ac 


Vwi 


(in 
int 
rgb 
rgb 
rgb 
Str 
for 


} 
s + 
str 


= new Color[] { 
temColor.activeCaption, 
temColor.activeCaptionBorder, 


temColor.windowText 
= new String[] { 


tiveCaption", 
tiveCaptionBorder", 


ndowText" 


t i = 0; i < strings.length; i++) 
[] rgb = new int[3]; 
[0] = colors[i].getRed(); 
[1] = colors[i].getGreen (); 
[2] = colors[i].getBlue(); 
ing s = "("; 
(int j = 0; Jj < 37 Jtt) { 
if (rgb[j] < 10) { 
s += 0; 
} 
if (rgb[j] < 100) { 
s += 0; 


} 
s t= rgb[jl; 
if (j < 2) { 


s t= ","; 


mJ Ws 


ings[i] = s + strings[i]; 
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Displaying Graphics, Images, and 
Animations 


The samples described in this section illustrate how to use graphics and images in 
Personal Profile. 


Note that implementations of Personal Profile must support the following image 
file formats: 


a GIF 89a 
m JPEG using the JFIF file exchange format 
a PNG version 1.0 


DrawDemo Sample 


This sample uses the draw and fi11 methods in the Graphics class. The shapes 
are drawn to fit inside each other to save space. Different colors are used (purple 
and gold) to make the shapes visible. 


. Lines 


The drawLine method is used to draw horizontal, vertical, and diagonal lines, 
resulting in a star-shaped figure: 


g.drawLine(x, y, x + w, y + h); 
g.drawLine(x + w / 2, y, x t+w/2, y + h); 
g.drawLine(x + w, y, x, y + hh); 
g.drawLine(x, y + hh / 2, x +w, y +h / 2); 


. Rectangles 


The drawRect, fillRect, draw3DRect, fill3DRect, drawRoundRect, 
fillRoundRect, and clearRect methods are used: 


g.drawRect (x, y, w, h); 

adjust (); 

g.fillRect(x, y, w, h); 
g.setColor (yellow) ; 

adjust (); 

g.draw3DRect (x, y, w, h, true); 
adjust (); 
g.fi1113DRect (x, y, w, h, true); 
g.setColor (purple) ; 
adjust (); 
g.drawRoundRect (x, y, w, h, 10, 10); 
adjust (); 
g.fillRoundRect (x, y, w, h, 10, 10); 
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adjust (); 
g.clearRect (x, y, W, 


. Ovals 


h); 


The drawOval, fillOval, drawArc, and fillArc methods are used. 


g.drawOval(x, y, w, 
adjust (); 
g.f1i1l0Oval(x, y, w, 
g.setColor (yellow) ; 
adjust (); 
g.drawArc(x, y, w, h, 135, 270); 
adjust (); 
g.fillArc(x, y, w, h, 135, 270); 


The drawPolygon, fillPolygon, and drawPolyline methods are used: 


. Polygons 


h); 


h); 


g.drawPolygon(array(x, x + w, X, X + WwW), 
*h/4, y +h), 
= 10 * d.width / 12; 
g.fillPolygon(array(x, x + w, xX, x + Ww), 
*h / 4, 
= 11 * d.width / 12; 
g.drawPolyline(array(x, x + Ww, X, X + W), 
*h / 4, 


y +h), 


y +h), 


4); 


4); 


4); 


The sample looks like this: 


Draw 


JV) 


PK 


Ov 


Following is the complete DrawDemo code: 


import java.awt.*; 


class DrawDemo extends Demo { 
static Color purple = 
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private 
private 
private 
private 
private 
private 
private 


static Color yellow = 


int 
int 
int 
int 
int 


x} 
Yi 
W; 
h; 
i; 


public DrawDemo() { 
this (400, 


200); 


new Color (0x7777AA) ; 
new Color (0xCCCCAA) ; 
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array (y, 


array(y, 


array(y, 


yth/ 4, 


yth/ 4, 


yth/ 4, 


y + 3 


y +3 


y+ 3 


public DrawDemo(int width, 


super (width, height); 


public void paint (Graphics g) { 
= getSize(); 


Dimension d 


int height) { 


i = (d.width + d.height) / 100; 
// lines 

x = 0; 

y = 0; 

w = d.width / 4 - i; 

h = d.height - 1; 

g.setColor (purple) ; 
g.drawLine(x, y, x + w, y + h); 
g.drawLine(x + w / 2, y, x + w/ 2, 
g.drawLine(x + w, y, x, y + h); 
g.drawLine(x, y + h / 2, x + w, y + 
// rvects 

x = 0; 

x = d.width / 4; 

y = 0; 

w = d.width / 4 - i; 

h = d.height - 1; 

g.setColor (purple) ; 
g.drawRect (x, y, w, h); 

adjust (); 

g.fillRect(x, y, w, h); 
g.setColor (yellow) ; 

adjust (); 

g.draw3DRect (x, y, w, h, true); 
adjust (); 

g.fi113DRect(x, y, w, h, true); 
g.setColor (purple) ; 

adjust (); 

g.drawRoundRect (x, y, w, h, 10, 10); 
adjust (); 

g.fillRoundRect (x, y, w, h, 10, 10); 
adjust (); 

g.clearRect (x, y, w, h); 

// circles 

x = 2 * d.width / 4; 

y = 0; 

w = d.width / 4 - i; 

h = d.height - 1; 

g.setColor (purple) ; 
g.drawOval(x, y, w, h); 

adjust (); 

g.fillOval(x, y, w, h); 
g.setColor (yellow) ; 

adjust (); 

g.drawArc(x, y, w, h, 135, 270); 
adjust (); 
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y + h); 


h / 2); 
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g.fillArc(x, y, w, h, 135, 270); 
// polys 

= 3 * d.width / 4; 

y = 0; 

w = d.width / 12 - i; 

h = d.height - 1; 
g 
g 


x 
| 


-setColor (purple) ; 
.drawPolygon(array(x, x + w, x, xX + w), array(y, y +h / 4, 
y+3*h / 4, y +h), 4); 
x = 10 * d.width / 12; 
g.fillPolygon(array(x, x + w, xX, x + w), array(y, y + h / 4, 
y+3* h/4, y +h), 4); 
x = 11 * d.width / 12; 
g.drawPolyline(array(x, x + w, xX, X¥ + w), array(y, y + h / 
4,y+3* h/ 4, y +h), 4); 


private void adjust() { 


x += i; 
y += 1; 
we=2 * 1; 
h—- 2 * i; 


private int[] array(int il, int i2, int i3, int i4) { 
int[] array = {il, i2, i3, i4}; 
return array; 


ImageDemo Sample 


The Image sample illustrates the image capabilities of Personal Profile. When you 
run it with the reference implementation, it looks like this: 


Ie Image al 


The first row of images shows that various image formats can be handled, by 
displaying GIF, JPG, and PNG images with a range of color and grayscale values. 
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The second row of images shows a transparent GIF image of Duke in various ways: 
m using drawImage 

m using drawImage with a background color 

m using drawImage with a buffered image 


The third row of images shows alphablending capabilities by drawing the Duke 
image after setting the alpha composite values to 0.0, 0.2, 0.4, 0.6, 0.8, and 1.0 using 
the set Composite method of Graphics2D. 


The images are all loaded with Toolkit’s get Image method, and the 
MediaTracker class, to ensure that all images are loaded before continuing. 


The buffered image is created using the GraphicsEnvironment, 
GraphicsDevice, and GraphicsConfiguration classes. The central method 
here is the createCompatibleImage method of GraphicsConfiguration: 


GraphicsEnvironment ge = 
GraphicsEnvironment.getLocalGraphicsEnvironment () ; 
GraphicsDevice gd = ge.getDefaultScreenDevice() ; 
GraphicsConfiguration gc = gd.getDefaultConfiguration(); 

int w = duke.getWidth (this); 

int h duke.getHeight (this) ; 

bi = gc.createCompatibleImage(w, h); 


The buffered image is then “drawn” by obtaining the Graphics object (using the 
getGraphics method) and calling standard graphics draw methods. In this case, a 
blue rectangle is drawn the same size as the image, followed by several rectangles 
of random colors and sizes, and finally the Duke image: 


Graphics big = bi.getGraphics(); 
big.setColor(Color.blue) ; 
big.fillRect (0, 0, w, h); 
for (int i = 0; i < 100; i++) { 
big.setColor(new Color((int) (Math.random() * 255), (int) 
(Math.random() * 255), (int) (Math.random() * 255))); 
big.fillRect((int) (Math.random() * w) - 10, (int) 
(Math.random() * h) - 10, (int) (Math.random() * w / 
10) + 4, (int) (Math.random() * h / 10) + 4); 
} 
big.drawImage (duke, 0, 0, w, h, O, O, w, h, this); 


The buffered image can be manipulated using the get RGB and set RGB methods 
when the mouse is clicked. Clicking the left mouse button makes the buffered 
image darker, and clicking the right button makes it lighter. Clicking the middle 
button restores the original colors, which are stored in the “original” field. 


public void mouseClicked(MouseEvent e) { 
int w = bi.getWidth (this); 
int h = bi.getHeight (this); 
if (original == null) { 
original = bi.getRGB(0, 0, w, h, null, 0, w); 
} 


int modifier = e.getModifiers(); 
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if ((modifier & InputEvent.BUTTON2_MASK) != 0) { 
bi.setRGB(0, 0, w, h, original, 0, w); 
repaint (); 


return; 

} 

int increment = -20; 

if ((modifier & InputEvent.BUTTON3_MASK) != 0) { 
increment = 20; 


} 
int[] rgb = bi.getRGB(0, 0, w, h, null, 0, w); 
for (int i = 0; i < rgb.length; itt) { 


int r = increment + ((rgb[i] & OxOOFFO000) >> 16); 
int g = increment + ((rgb[i] & OxOOOOFFOO) >> 8); 
int b = increment + ((rgb[i] & OxOOOOOOFF) >> 0); 
PS S259 oe) 255% 

g = .9 < 255.2? -g £ 255; 

b-= b <. 255.2?) b #255; 

5 a — ies ce a 0 et aes 0; 

G=g>0?g 0; 

b By Oe bs 

rgb[i] = rgb[i] & OxFF0O00000; 

rgb[i] += (r << 16); 

rgb[i] += (g << 8); 

rgb[i] += b; 


} 
bi.setRGB(0, 0, w, h, rgb, 0, w); 
repaint (); 


} 


Image scaling capabilities are demonstrated by using the drawImage methods that 
take coordinates and sizes, for the source and destination, to scale the images to fit 
the size of the image component. 


The sample demonstrates the effect of the set XORMode method on image drawing. 
You can drag the mouse across the Image sample display and it draws a Duke in 
XOR mode: 


public void mouseDragged(MouseEvent e) { 
Dimension d = getSize(); 
int w = d.width / 3; 
int h = d.height / 3; 
Graphics g = getGraphics(); 
g.setXORMode (Color.black); 
if (drag) { 
g.drawImage(duke, xorX, xorY, xorX + w, xorY + h, O, O, 
duke.getWidth(this), duke.getHeight (this), this); 


xorX e.getX() - w / 2; 

xorY = e.getY() - w / 2; 

g.drawImage(duke, xorX, xorY, xorX + w, xorY + h, O, O, 
duke.getWidth(this), duke.getHeight (this), this); 

drag = true; 


144 Personal Profile Programmer’s Guide * September 2002 


import 
import 
import 


public 
{ 


public void mouseReleased(MouseEvent e) { 
Dimension d = getSize(); 
int w = d.width / 3; 
int h = d.height / 3; 
if (drag) { 
Graphics g = getGraphics(); 
g.setXORMode (Color.black) ; 


g.drawImage(duke, xorX, xorY, xorX + w, xorY + h, O, O, 


duke.getWidth(this), duke.getHeight (this), this); 


} 
drag = false; 


} 


Following is the complete sample code: 


java.awt.*; 
java.awt.event.*; 
java.awt.image.*; 


class ImageDemo extends Demo implements MouseMotionListener, MouseListener 


private Image gif; 
private Image jpg; 
private Image png; 
private Image duke; 
private BufferedImage bi; 
private int[] original; 
private boolean drag; 
private int xorx; 

private int xoryY; 


public ImageDemo() { 


this (200, 130); 


public ImageDemo(int width, int height) { 


super (width, height); 
Toolkit toolkit = Toolkit.getDefaultToolkit(); 
gif = toolkit.getImage("images/test.gif"); 
jpg = toolkit.getImage("images/test.jpg") ; 
png = toolkit.getImage ("images/test.png") ; 
duke = toolkit.getImage ("images/duke.gif") ; 
MediaTracker tracker = new MediaTracker (this) ; 
tracker.addImage(gif, 1); 
tracker.addImage (jpg, 2); 
tracker.addImage(png, 3); 
tracker.addImage (duke, 4); 
try { 
tracker.waitForID(1); 
tracker.waitForID (2); 
tracker.waitForID (3); 
tracker.waitForID (4); 
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} catch (InterruptedException ie) { 
System.out.printin(ie); 

} 

GraphicsEnvironment ge = 
GraphicsEnvironment.getLocalGraphicsEnvironment () ; 

GraphicsDevice gd = ge.getDefaultScreenDevice(); 

GraphicsConfiguration gc = gd.getDefaultConfiguration(); 

int w = duke.getWidth (this); 


int h = duke.getHeight (this); 
bi = gc.createCompatibleImage(w, h); 
while (bi == null) { 
try { 


Thread.sleep (100); 
} catch (InterruptedException ie) { 
} 
} 
Graphics big = bi.getGraphics(); 
big.setColor(Color.blue) ; 
big.fillRect(0, 0, w, h); 
for (int i = 0; i < 100; i++) { 
big.setColor(new Color((int) (Math.random() * 255), (int) 
(Math.random() * 255), (int) (Math.random() * 255))); 
big.fillRect((int) (Math.random() * w) - 10, (int) 
(Math.random() * h) - 10, (int) (Math.random() * w / 
10) + 4, (int) (Math.random() * h / 10) + 4); 
} 
big.drawImage (duke, 0, 0, w, h, 0, 0O, w, h, this); 
addMouseMotionListener (this) ; 
addMouseListener (this); 


public void paint(Graphics g) { 

Dimension d = getSize(); 

int w = d.width / 3; 

int h = d.height / 3; 

g.setColor(Color.gray) ; 

for (int i = 2; i < d.height; i += 4) { 
g.drawLine(0, i, d.width, i); 

} 

int x = 0; 

int y = 0; 

g.drawImage(gif, x, y, x + w, y + h, 0, 0, gif.getWidth(this), 
gif.getHeight (this), this); 

x += w; 

g.drawImage(jpg, x, y, x + w, y + h, O, O, jpg.getWidth(this), 
jpg.getHeight (this), this); 

x += w; 

g.drawImage(png, x, y, x + w, y + h, O, O, png.getWidth(this), 
png.getHeight (this), this); 

x = 0; 

y t= h; 
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g.drawImage (duke, x, y, x + w, y + h, O, O, 
duke.getWidth(this), duke.getHeight (this), this); 
x += w; 
g.drawImage (duke, x, y, x + w, y + h, O, O, 
duke.getWidth(this), duke.getHeight (this), Color.red, this); 
x += w; 
g.drawImage(bi, x, y, x + w, y + h, O, O, bi.getWidth(this), 
bi.getHeight (this), this); 
x = 0; 
y t= h; 
((Graphics2D) g).setComposite (AlphaComposite.getInstance 
(AlphaComposite.SRC_OVER, 0.0f)); 
g.drawImage (duke, x, y, w / 2, h, this); 
x t= w / 2; 
((Graphics2D) g) .setComposite (AlphaComposite.getInstance 
(AlphaComposite.SRC_OVER, 0.2f)); 
g.drawImage (duke, x, y, w / 2, h, this); 
x t= w / 2; 
((Graphics2D) g) .setComposite (AlphaComposite.getInstance 
(AlphaComposite.SRC_OVER, 0.4f)); 
g.drawImage (duke, x, y, w / 2, h, this); 
x t= w / 2; 
((Graphics2D) g) .setComposite (AlphaComposite.getInstance 
(AlphaComposite.SRC_OVER, 0.6f)); 
g.drawImage (duke, x, y, w / 2, h, this); 
x t= w / 2; 
((Graphics2D) g) .setComposite (AlphaComposite.getInstance 
(AlphaComposite.SRC_OVER, 0.8f)); 
g.drawImage (duke, x, y, w / 2, h, this); 
x t= w / 2; 
((Graphics2D) g).setComposite (AlphaComposite.getInstance 
(AlphaComposite.SRC_OVER, 1.0f)); 
g.drawImage (duke, x, y, w / 2, h, this); 


public void mouseDragged(MouseEvent e) { 


Dimension d = getSize(); 

int w = d.width / 3; 

int h = d.height / 3; 

Graphics g = getGraphics(); 

g.setXORMode (Color.black) ; 

if (drag) { 

g.drawImage(duke, xorX, xorY, xorX + w, xorY + h, O, O, 

duke.getWidth(this), duke.getHeight (this), this); 

} 

xorX = e.getX() - w/ 2; 

xorY = e.getY() - w/ 2; 

g.drawImage(duke, xorX, xorY, xorX + w, xorY + h, O, O, 
duke.getWidth(this), duke.getHeight (this), this); 

drag = true; 
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public void mouseMoved(MouseEvent e) { 


} 


public void mouseClicked(MouseEvent e) { 

int w = bi.getWidth (this) ; 

int h = bi.getHeight (this); 

if (original == null) { 
original = bi.getRGB(0, 0, w, h, null, 0, w); 

} 

int modifier = e.getModifiers(); 

if ((modifier & InputEvent.BUTTON2_MASK) != 0) { 
bi.setRGB(0, 0, w, h, original, 0, w); 
repaint (); 


return; 

} 

int increment = -20; 

if ((modifier & InputEvent.BUTTON3_MASK) != 0) { 
increment = 20; 


} 
int[] rgb = bi.getRGB(0, 0, w, h, null, O, w); 
for (int i = 0; i < rgb.length; i++) { 


int r = increment + ((rgb[i] & OxO0OFF0O000) >> 16); 
int g = increment + ((rgb[i] & OxOOOOFFO00) >> 8); 
int b = increment + ((rgb[i] & OxOOQOOOOFF) >> 0); 
BS <2 Si Pee se 2554 

g = 9g <= 255 Pg 3 255; 

bP = bs < 255°? bd. 255; 

BS S02 ar 6 1 0F 

G=g9>0?q: 0; 

b GSU? eS Oe 


rgb[i] = rgb[i] & OxFF000000; 
rgb[i] += (r << 16); 
rgb[i] += (g << 8); 
rgb[i] += b; 
} 
bi.setRGB(0, 0, w, h, rgb, 0, w); 
repaint (); 


public void mouseEntered(MouseEvent e) { 


public void mouseExited(MouseEvent e) { 


public void mousePressed(MouseEvent e) { 


public void mouseReleased(MouseEvent e) { 
Dimension d = getSize(); 
int w = d.width / 3; 
int h = d.height / 3; 
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if (drag) { 
Graphics g = getGraphics(); 
g.setXORMode (Color.black) ; 
g.drawImage(duke, xorX, xorY, xorX + w, xorY + h, O, O, 
duke.getWidth(this), duke.getHeight (this), this); 
} 
drag = false; 


AnimatorDemo Sample 


This sample displays an animated GIF: 


iE) Animator (=a) 


& 


Following is the AnimatorDemo.java source code: 


import java.awt.*; 


class AnimatorDemo extends Demo { 
private Image image; 


public AnimatorDemo() { 


Toolkit toolkit = Toolkit.getDefaultToolkit(); 
image = toolkit.getImage ("images/duke-animated.gif"); 


public void paint (Graphics g) { 
g.drawImage(image, 0, 0, this); 
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Working with Fonts 


Personal Profile uses the same fonts as the J2SE environment. The following 
samples show how to use fonts. 


FontDemo Sample 


This sample shows the standard fonts, serif, sans serif, monospaced, Dialog, 
DialogInput, and Symbol using the PLAIN, BOLD, ITALIC, and BOLD+ITALIC 


styles. 


The paint method creates the fonts from an array of font names inducing the 
drawString method, displays the font size and name in PLAIN style, and the 
strings BOLD, ITALIC, and BOLD+ITALIC in the corresponding styles. 


The sample looks like this: 


EI Font ial 
13° serif BOLD/TALIC BOLD+ITALIC 
13 sansserif BOLDITALIC BOLD+HTALIC 
13 monospaced BOLD ITALIC BOLD+ITALIC 
13 Dialog BOLD/TALIC BOLDHTALIC 
13 DialogInput BOLD ITALIC BOLD+ETALIC 
13 Symbol BOLD ITALIC BOLD+ITALIC 


fle: | 


Following is the FontDemo.java sample code: 


import java.awt.*; 


public class FontDemo extends Demo { 
private static String[] fontNames = new String[] { 
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}; 


"serif", 
"Sansserif", 
"monospaced", 
"Dialog", 
"DialogInput", 
"Symbol" 


private int fontSize; 
private int charWidth; 
private boolean resize; 


public FontDemo() { 


this (440, 110); 
resize = true; 
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public FontDemo(int fontSize) { 
this (440, 110, fontSize); 


public FontDemo(int width, int height) { 
this (width, height, 16); 
resize = true; 


public FontDemo(int width, int height, int fontSize) 
super (width, height); 
this.fontSize = fontSize; 


public void paint (Graphics g) { 
Dimension d = getSize(); 
int w = d.width - 1; 
int h = d.-height - 1; 
g.setColor(Color.black) ; 
if (resize) { 
resize(); 


} 


Font font = new Font ("monospaced", Font.BOLD + Font.ITALIC, 


fontSize); 
FontMetrics fm = g.getFontMetrics (font) ; 
charWidth = fm.charWidth(’0’); 
int y = fontSize + 2; 
for (int i = 0; i < fontNames.length; i++) { 
int x = 4; 


font = new Font (fontNames[i], Font.PLAIN, fontSize); 


.setFont (font); 

.drawString("" + fontSize, x, y); 
+= 3 * charWidth; 
-drawString(fontNames[i], x, y); 
+= 12 * charWidth; 


x Q x QQ 


font = new Font (fontNames[i], Font.BOLD, fontSize); 


g.setFont (font) ; 
g.drawString("BOLD", x, y); 
x += 5 * charWidth; 


font = new Font(fontNames[i], Font.ITALIC, fontSize); 


g.setFont (font) ; 
g.drawString("ITALIC", x, y); 
x += 7 * charWidth + 4; 


font = new Font (fontNames[i], Font.BOLD + Font.ITALIC, 


fontSize); 
g.setFont (font); 
g.drawString("BOLD+ITALIC", x, y); 
y += fontSize; 
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private void resize() { 
Dimension d = getSize(); 
int w = d.width / (3 + 12 +5 + 7+ 11) + 4; 
int h = d.height / fontNames.length; 
fontSize =w.<h ?w: h; 


FontMetrics Sample 


This sample displays the letter g at the junction of two lines, which represent the 
left-hand side and the base-line of the letter. 


It then displays the font size and the values returned by the FontMetrics methods, 
such as getAscent, getDescent, and so on. 


It looks like this: 


ei FontMetrics | -|_i] 


Following is the FontMetricsDemo.java sample code: 


import java.awt.*; 


public class FontMetricsDemo extends Demo { 
private char character = 'g’; 
private int fontSize; 
private int smallFontSize; 
private boolean resize; 


public FontMetricsDemo() { 
this (400, 300); 


resize = true; 


public FontMetricsDemo(int fontSize) { 
this(180, 110, fontSize); 


public FontMetricsDemo(int width, int height) { 
this (width, height, 100); 
resize = true; 
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public FontMetricsDemo(int width, int height, int fontSize) { 
super (width, height); 
this.fontSize = fontSize; 


public void paint(Graphics g) { 
Dimension d = getSize(); 
int w = d.width - 1; 
int h = d.height - 1; 
g.setColor(Color.black) ; 
if (resize) { 
resize(); 
} 
Font font = new Font("Dialog", Font.PLAIN, fontSize); 
g.setFont (font); 
FontMetrics fm = g.getFontMetrics (font) ; 
int charWidth = fm.charWidth (character) ; 


int ascent = fm.getAscent (); 

int descent = fm.getDescent (); 

int height = fm.getHeight (); 

int leading = fm.getLeading(); 

int maxAdvance = fm.getMaxAdvance(); 
int maxAscent = fm.getMaxAscent (); 
int maxDescent = fm.getMaxDescent (); 
g.setColor(Color.black) ; 

int x = 4; 

int y = ascent; 


g.drawString("" + character, x, y); 
g.drawLine(x, y, x + charWidth, y); 
g.drawLine(x, y - ascent, x, y + descent); 
w= 3 * d.width / 2 / 15 / 2; 
= d.height /9/2-1; 
smallFontSize =w<h ?we: hj; 
smallFontSize = smallFontSize > 10 ? smallFontSize : 10; 
x = charWidth + 8; 
y = 4 + smallFontSize; 


font = new Font ("monospace", Font.PLAIN, smallFontSize) ; 
g.setFont (font); 

g.drawString("font size: " + fontSize, x, y); 

y += smallFontSize; 

g.drawString("ascent: " + ascent, x, y); 

y t= smallFontSize; 

g.drawString("descent: " + descent, x, y); 

y t= smallFontSize; 

g.drawString("height: " + height, x, y); 

y t= smallFontSize; 

g.drawString("leading: " + leading, x, y); 

y t= smallFontSize; 

g.drawString("maxAdvance: " + maxAdvance, x, y); 
y t= smallFontSize; 

g.drawString("maxAscent: " + maxAscent, x, y); 

y += smallFontSize; 
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g.drawString("maxDescent: " + maxDescent, x, y); 
y += smallFontSize; 
g.drawString("charWidth: " + charWidth, x, y); 

} 


private void resize() { 
Graphics g = getGraphics(); 
Dimension d = getSize(); 
int w = 3 * d.width / 2 / 2; 
int h = 4 * d.height / 5; 
fontSize =w.<h?wi: h; 
w= 3 * d.width / 2/15 / 2; 
h = d.height / 9 / 2 - 1; 
smallFontSize =w<h ?w: h; 
smallFontSize = smallFontSize > 10 ? smallFontSize : 10; 


Working with Cursors 


Some implementations of Personal Profile may not support the variety of cursors 

defined in the API. For instance, a stylus-based device may not support cursors at 
all, or may only support a few of the cursor types. Also, a cursor’s representation 
may not be unique: an implementation may use a single cursor image to represent 
several, or even all, of the cursor types specified in the API. 


Because not all devices support cursors, or support a subset of cursors, your 
implementation should not be totally cursor-based if you want to run on these 
devices. You should make sure that there are alternate ways to indicate the same 
functions as the cursor indicates, so the user doesn’t get stuck. 


MouseDemo Sample 


This sample shows the x and y coordinates of the mouse cursor inside a mouse as 
it is moved or dragged across the component. It also alters the outline of the 
sample when the mouse cursor enters or exits the demo, and shows which mouse 
buttons are pressed or released. 


It does this by implementing the MouseListener and MouseMotionListener 
interfaces. 


Note that the aspect ratio is used to maintain a fixed width to height ratio in the 
graphic. 
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The sample looks like this: 


Following is the MouseDemo,java sample code: 


import java.awt.*; 
import java.awt.event.*; 


public class MouseDemo extends Demo implements MouseListener, MouseMotionListener 


{ 

private boolean inside; 

private static final float ASPECT_RATIO = 0.6f; 
private int posxX; 

private int posyY; 

private Color[] buttonColors = new Color[3]; 


public MouseDemo() { 
this(120, 200); 


public MouseDemo(int width, int height) { 
super (width, height); 
addMouseListener (this); 
addMouseMotionListener (this); 


public void paint (Graphics g) { 
Dimension d = getSize(); 


float wf = d.width; 
float hf = d.height; 


if (ASPECT_RATIO > 1.0) { 
if (hf < wf / ASPECT_RATIO) { 


wf = hf * ASPECT_RATIO; 
} else { 
hf = wf / ASPECT_RATIO; 


if (wf < hf * ASPECT_RATIO) { 


hf = wf / ASPECT_RATIO; 
} else { 
wf = hf * ASPECT_RATIO; 
} 
} 
int w = (int) wf - 1; 
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int h 
int x 
int y 


(ianthy AEH 1s 
(d.width - w) / 2; 
(d.height - h) / 2; 


g.setColor(Color.white) ; 

g.fillRect(0, 0, w, h); 

for (int = 07. 1:-< Sp t+) 4 
buttonColors[i] = Color.lightGray; 

} 

paintMouseButtons(); 

paintMousePosition(); 

paintMouselInside(); 


public void mouseClicked(MouseEvent e) { 


} 


public void mouseEntered(MouseEvent e) { 
inside = true; 
paintMouselInside(); 


public void mouseExited(MouseEvent e) { 
inside = false; 
paintMouselInside(); 


public void mousePressed(MouseEvent e) { 

int modifier = e.getModifiers(); 

if ((modifier & InputEvent.BUTTON1_MASK) != 0) 
buttonColors[0] = Color.darkGray; 

} 

if ((modifier & InputEvent.BUTTON2_MASK) != 0) 
buttonColors[1] = Color.darkGray; 

} 

if ((modifier & InputEvent.BUTTON3_MASK) != 0) 
buttonColors[2] = Color.darkGray; 


} 


paintMouseButtons (); 


public void mouseReleased(MouseEvent e) { 


int modifier = e.getModifiers(); 

if ((modifier & InputEvent.BUTTON1_MASK) != 0) 
buttonColors[0] = Color.lightGray; 

} 

if ((modifier & InputEvent.BUTTON2_MASK) != 0) 
buttonColors[1] = Color.lightGray; 

} 

if ((modifier & InputEvent.BUTTON3_MASK) != 0) 
buttonColors[2] = Color.lightGray; 
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paintMouseButtons(); 


public void mouseDragged(MouseEvent e) 


mouseMoved (e) ; 


public void mouseMoved (MouseEvent e) { 


posX = e.getX(); 
posY = e.getY(); 
paintMousePosition(); 


private void paintMouselInside() 
Graphics g = getGraphics(); 
if (inside) { 
g.setColor(Color.red); 
} else { 
g.setColor(Color.black) ; 
} 


Dimension d = getSize(); 


{ 


float wf = d.width; 
float hf = d.height; 
if (ASPECT_RATIO > 1.0) { 
if (hf < wf / ASPECT_RATIO) { 
wf = hf * ASPECT_RATIO; 
} else { 
hf = wf / ASPECT_RATIO; 
} 
} else { 
if (wf < hf * ASPECT_RATIO) { 
hf = wf / ASPECT_RATIO; 
} else { 
wf = hf * ASPECT_RATIO; 
} 
} 
int w (nt). wk -="13 
int h = (int) Af + 1; 
int x = (d.width - w) / 2; 
int y = (d.height - h) / 2; 


g.drawRect (xX, y, W, h); 


private void paintMouseButtons () 
Dimension d = getSize(); 


float wf = d.width; 
float hf = d.height; 
if (ASPECT_RATIO > 1.0) { 


if 


{ 


(hf < wf / ASPECT_RATIO) { 
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wf = hf * ASPECT_RATIO; 
} else { 
hf = wf / ASPECT_RATIO; 
} 
} else { 
if (wf < hf * ASPECT_RATIO) { 
hf = wf / ASPECT_RATIO; 
} else { 
wf = hf * ASPECT_RATIO; 
} 
} 
int w = (int) wf - 1; 
int h = (int) hf - 1; 
int x = (d.width - w) / 2; 
int y = (d.height - h) / 2; 


Graphics g = getGraphics(); 
for (int. = 0; 4-<-S} a4++) 4 
g.setColor(buttonColors[i]); 
g.fillRect(i * w/3+1+x, y+1, w/3- 2, h/ 3); 
g.setColor(Color.black) ; 
g.drawRect(i * w/3+1+x, y+1, w/3- 2, h/ 3); 


private void paintMousePosition() { 
Dimension d = getSize(); 
float wf = d.width; 
float hf = d.height; 


if (ASPECT_RATIO > 1.0) { 
if (hf < wf / ASPECT_RATIO) { 
wf = hf * ASPECT_RATIO; 
} else { 
hf = wf / ASPECT_RATIO; 
} 
} else { 
if (wf < hf * ASPECT_RATIO) { 
hf = wf / ASPECT_RATIO; 


} else { 
wf = hf * ASPECT_RATIO; 
} 
} 
int w = (int) wf - 1; 
int h = (int) hf - 1; 
int x = (d.width - w) / 2; 
int y = (d.height - h) / 2; 


Graphics g = getGraphics(); 
g.setColor(Color.white) ; 

g.fillRect(1, h / 3 +2, w- 2, 2 * h / 3 - 2); 
g.setColor(Color.black); 
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int fontSize = 10 + (w+ h) / 40 -w/h-h/w; 

Font font = new Font ("Monospaced", Font.PLAIN, fontSize); 

g.setFont (font); 

g.drawString("x:" + posX, w / 6+ x, 2 * h / 3 - fontSize / 2 + 
y); 

g.drawString("y:" + posY, w / 6+ x, 2 * h / 3 + fontSize / 2 + 
y); 


CursorDemo Sample 


This sample displays the available mouse cursor shapes. The paint method draws 
six rectangles to display the Default, Cross hair, Hand, Move, Text, and Wait 
cursors, and a border with corners to display the different Resize cursors. By 
moving the mouse over the rectangles or borders, it will automatically change the 
cursor to the appropriate shape. 


It achieves this by implementing the MouseMot ionListener and, depending on 
the location of the cursor, setting the cursor to the appropriate type using the 
setCursor method. The actual instance of Cursor that is passed to the 
setCursor method is obtained using the getPredefinedCursor method of the 
Cursor class. 


The sample looks like this: 


Ba Cursor Tory 


Following is the sample code: 


import java.awt.*; 
import java.awt.event.*; 


public class CursorDemo extends Demo implements MouseMotionListener { 
public CursorDemo() { 
this (400, 300); 


public CursorDemo(int width, int height) { 
super (width, height); 
addMouseMotionListener (this); 


public void paint(Graphics g) { 
Dimension d = getSize(); 
int w = d.width - 1; 
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int h d.height - 1; 

aint <t (w + h) / 40; 

int c = (wth) / 15; 

int fontSize = (w +h) / 26; 

Font font = new Font ("Monospaced", Font.PLAIN, fontSize); 


g.setColor(Color.lightGray) ; 

g.fillRect(0, 0, w, h); 

g.setColor(Color.white) ; 

g.fillRect(t, t, w-2* t, h- 2 * t); 

g.setColor(Color.gray) ; 

g.drawRect (0, 0, w, h); 

g.drawRect(t, t, w-2* t, h- 2 * t); 

// corners 

g.drawLine(0, c, t, c); 

g.drawLine(w - t, c, w, Cc); 

g.drawLine(0, h - c, t, h- c); 

g.drawLine(w - t, h - c, w, h - c); 

g.drawLine(c, 0, c, t); 

g.drawLine(c, h - t, c, h); 

g.drawLine(w - c, 0, w- c, t); 

g.drawLine (w Gy. t, w c, h); 

// rectangles 

g.drawLine(w / 2, t, w/ 2, h-t); 

g.drawLine(t,;. t +. (h =.2° * t)-/ 3; ‘woot, E+ (hh -- 2 * t) /°3)3 

g.drawLine(t, t + 2 * (h- 2 * t) / 3, w-t, t +2 * (h - 
2 ee fi <3) 

g.setColor(Color.black) ; 

g.setFont (font); 

g.drawString("Default", t + 4, t +1 * (h-2* t) / 3 - 4); 

g.drawString("Hand", t+4,t+2* (h- 2 * t) / 3 - 4); 

g.drawString("Text", t+4,t+3* (h-2* t) / 3 - 4); 

g.drawString("Cross hair", w/2 +4, t +1* (h-2* t) / 
Sued); 

g.drawString("Move", w/2+4, t +2 * (h-2* t) / 
sem 4)y 

g.drawString("Wait", w/2+ 4, t+3* (h-2* t) / 
By eA) 


public void mouseDragged(MouseEvent e) { 


} 


public void mouseMoved (MouseEvent e) { 

int posX = e.getX(); 

int posY = e.getY(); 

Dimension d = getSize(); 
int w = d.width - 1; 

int h = d.height - 1; 

int t = (w+ h) / 40; 

int c = (wth) / 15; 

Cursor cursor = 

Cursor.getPredefinedCursor (Cursor.DEFAULT_CURSOR) ; 
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if 


(posX >= 0 && posX <= w && posY >= 0 && posY <= h) { 
cursor = 
Cursor.getPredefinedCursor (Cursor.NW_RESIZE_CURSOR) ; 


if 


(posX >= 0 
cursor = 
Cursor. 
(posX >= 0 
cursor = 
Cursor. 


(posX >= c 
cursor = 


Cursor. 


(posX >= w 
cursor = 


&& posY >= c) { 
getPredefinedCursor (Cursor.W_RESIZE_CURSOR) ; 


&& posY >= h -c) { 


getPredefinedCursor (Cursor.SW_RESIZE_CURSOR) ; 


&& posY >= 0) { 
getPredefinedCursor (Cursor.N_RESIZE_CURSOR) ; 


—- c && posY >= 0) { 


Cursor.getPredefinedCursor (Cursor.NE_RESIZE_CURSOR) ; 


(posX >= w 
cursor = 


Cursor. 


(posX >= Cc 
cursor = 


Cursor. 


(posX >= w 
cursor = 


Cursor. 


(posX >= t 
posx Ww 
posYy >= t 
posy <= t 
cursor = 


Cursor. 


(posX >= t 
posx Ww 
posY += ft 
posY <= t 
cursor = 


Cursor. 


(posX >= t 
posx Ww 
posYy >= t 
posy <=h 
cursor = 


Cursor. 


-— t && posY >= c) { 


getPredefinedCursor (Cursor.E_RESIZE_CURSOR) ; 
&& posY >=h - t) { 
getPredefinedCursor (Cursor.S_RESIZE_CURSOR) ; 


- c && posY >=h- oc) { 


getPredefinedCursor (Cursor.SE_RESIZE_CURSOR) ; 


&& 
/ 2 && 

&& 

+ ihe S52) Ey LSet 


getPredefinedCursor (Cursor.DEFAULT_CURSOR) ; 


getPredefinedCursor (Cursor.TEXT_CURSOR) ; 
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if (posX >= w / 2 && 
posx <=w-t && 
posY >= t && 
POSY <> te to(he a s2° ey Sy 
cursor = 
Cursor.getPredefinedCursor (Cursor.CROSSHAIR_CURSOR) ; 
} 


if (posX >= w / 2 && 
posx <=w-t && 
posy >=t + (h- 2 * t) / 3 && 
posy <=t+2* (h- 2 * t) / 3) { 
cursor = 
Cursor.getPredefinedCursor (Cursor.MOVE_CURSOR) ; 
} 
if (posX >= w / 2 && 
posxX <=w-t && 
posy >=t +2 * (h-2* t) / 3 && 
posY <=h-t) { 
cursor = 
Cursor.getPredefinedCursor (Cursor.WAIT_CURSOR) ; 


} 


setCursor (cursor); 
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Publishing and Subscribing to Events 


The KeyboardDemo sample shows the values returned by KeyEvents when 
keyboard keys are pressed. It draws a keyboard and whenever a key is pressed, the 
getKeyChar, getKeyCode, and getModifiers methods are called and their 
values are displayed. 


To accomplish this, the sample implements the KeyListener interface: 


public class KeyboardDemo extends Demo implements KeyListener { 


And in the keyPressed method, which is called in the AWT event thread, it calls 
the paintEvent method: 


public void keyPressed(KeyEvent e) { 
paintEvent (e) ; 


} 


This gets the values that are displayed in the keyboard. The key code value is 
obtained from a hashtable that maps all the key code constants in the KeyEvent 
class to corresponding strings. 
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The sample looks like this: 


ie) Keyboard Ee) 
000 


chee: ‘y' (122) 
code: Et) 
ode 


Following is the KeyboardDemo.java sample code: 


import java.awt.*; 
import java.awt.event.*; 


import java.util.*; 

public class KeyboardDemo extends Demo implements KeyListener { 
private static final Hashtable table; 
private static final float ASPECT_RATIO = 2.5f; 
private Font font = new Font ("Monospaced", Font.PLAIN, 12); 
private String keyCharString = ""; 
private String keyCodeString = ""; 
private String modifierString = ""; 


public KeyboardDemo() { 
this(500, 200); 


public KeyboardDemo(int width, int height) { 
super (width, height); 
addKeyListener (this) ; 
addMouseListener (new MouseAdapter() { 
public void mouseClicked(MouseEvent e) { 
KeyboardDemo.this.requestFocus(); 


public void mouseEntered(MouseEvent e) { 
KeyboardDemo.this.requestFocus (); 


})F 


public void paint (Graphics g) { 
Dimension d = getSize(); 
float wf = d.width; 
float hf = d.height; 
if (ASPECT_RATIO > 1.0) { 
if (hf < wf / ASPECT_RATIO) { 
wf = hf * ASPECT_RATIO; 
} else { 
hf = 


wf / ASPECT_RATIO; 
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} else { 
if (wf < hf * ASPECT_RATIO) { 
hf = wf / ASPECT_RATIO; 


} else { 
wf = hf * ASPECT_RATIO; 
} 
int w = (int) wf - 1; 
int h = (int) hf - 1; 
int x = (d.width - w) / 2; 
int y = (d.height - h) / 2; 


g.setColor(Color.lightGray) ; 

g.fillRect(x, y, w, h); 

g.setColor(Color.black); 

g.drawRect (x, y, w, h); 

g.setColor(Color.white) ; 

g.fillRect(x + 6, y + 6, 4 * w/ 5, h/ 6); 

g.fillRect(x + 6, y+ 6+h /6+ 6, w- 12 
— 6); 

g.setColor(Color.gray) ; 


g.drawRect (x + 6, y + 6, 4 * w/ 5, h/ 6); 


g.drawRect (x + 6, y+ 6+h / 6+ 6, w- 12 
— 6); 
// LEDs 


g.drawRect (x + 4 * w/5+1* w/ 20, 


a) 
uo 


g.drawRect(x + 4* w/5+2 * w / 20, y + 
g.drawRect (x + 4* w/5 +3 * w/ 20, y + 


paintStrings(); 


public void keyPressed(KeyEvent e) { 


paintEvent (e); 


public void keyReleased(KeyEvent e) {} 


public void keyTyped(KeyEvent e) {} 


private void paintEvent (KeyEvent e) { 


keyCharString = "char: "; 

keyCodeString = "code: "; 

modifierString = "mods: "; 

char keyChar = e.getKeyChar(); 

if (keyChar == KeyEvent.CHAR_UNDEFINED) { 


keyCharString += "undefined"; 
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phe = 66. 


Fras nen Coe 2 


6 + 6) 


30); 
30); 
30); 


} else { 
keyCharString += "’" + keyChar + "'"; 
} 
keyCharString += " ("+ (int) keyChar + ")"; 
int keyCode = e.getKeyCode(); 
Integer key = new Integer (keyCode) ; 
String value = (String) table.get (key); 


if (value == null) { 
value = "unknown"; 
} 
keyCodeString += value + " ("+ keyCode + ")"; 
int modifier = e.getModifiers(); 
if ((modifier & InputEvent.SHIFT_MASK) != 0) { 
if (keyCode != KeyEvent.VK_SHIFT) { 


modifierString += "SHIFT "; 


if ((modifier & InputEvent.CTRL_MASK) != 0) { 
if (keyCode != KeyEvent.VK_CONTROL) { 
modifierString += "CONTROL "; 


if ((modifier & InputEvent.ALT_MASK) != 0) { 
if (keyCode != KeyEvent.VK_ALT) { 
modifierString += "ALT "; 


if ((modifier & InputEvent.ALT_GRAPH_MASK) != 0) { 
if (keyCode != KeyEvent.VK_ALT_GRAPH) { 
modifierString += "ALT GRAPH "; 


if ((modifier & InputEvent.META_MASK) != 0) { 
if (keyCode != KeyEvent.VK_META) { 


modifierString += "META "; 


} 
paintStrings(); 


private void paintStrings() { 
Graphics g = getGraphics(); 
Dimension d = getSize(); 


float wf = d.width; 
float hf = d.height; 


if (ASPECT_RATIO > 1.0) { 


if (hf < wf / ASPECT_RATIO) { 
wf = hf * ASPECT_RATIO; 

} else { 
hf = wf / ASPECT_RATIO; 
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if (wf < hf * ASPECT_RATIO) { 
hf = wf / ASPECT _RATIO; 


(0) 
ee 
0) 
0) 
| to 


hf * ASPECT_RATIO; 


w = (int) wf - 1; 
int h = (int) hf - 1; 

x = (d.width - w) / 2; 

y = (d.height - h) / 2; 


g.setColor(Color.white) ; 
g.fillRect(x +7, y+6+h/6+6+1, w- 14, h- (6+h/6+ 6) -6-1); 
g.setColor(Color.black) ; 
int fontSize = 2+ (w+t+h) /40-w/h-h/w; 
Font font = new Font ("Monospaced", Font.PLAIN, fontSize); 
.setFont (font); 
t= 6+ h/6+6+ 4; 
+= fontSize; 
-drawString(keyCharString, x + 16, y); 
+= fontSize; 
-drawString(keyCodeString, x + 16, y); 
+= fontSize; 
-drawString(modifierString, x + 16, y); 


aK aKaQakK kK YQ 


} 
static { 
int keys[] = { 
KeyEvent.VK_A, KeyEvent.VK_B, KeyEvent.VK_C, 
KeyEvent.VK_D, 
KeyEvent.VK_E, KeyEvent.VK_F, KeyEvent.VK_G, 
KeyEvent.VK_H, 


KeyEvent .VK_UP 
hi 
String values[] = { 
"A", VB ia MD 2 
Ey i "go", es ae 


ee 
hi 
table = new Hashtable (keys.length) ; 
for (int i = 0; i < keys.length; ++i) { 
table.put (new Integer(keys[i]), values[i]); 
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Working with Layouts 


The LayoutDemo sample is a combination of the FlowLayout, BorderLayout, 
GridLayout, GridBagLayout, CardLayout, and NullLayout samples. 


The FlowLayout sample creates seven buttons of different widths to show that the 
FlowLayout manager will respect the preferred sizes of its components. Therefore 
the “2” button is very small whereas the “threethreethree” button is rather wide. 


The BorderLayout sample creates five buttons and puts them in the North, South, 
East, West, and Center positions by calling the add method that takes a second 
String parameter. It illustrates how the buttons are resized to fit into the positions, 
thereby making the center button the largest. 


The GridLayout sample creates a GridLayout of three rows and two columns and 
illustrates how buttons are stretched to fill the grid. 


The GridBagLayout sample shows how the programmer has far more control over 
the positioning of buttons. Note that whereas FlowLayout and GridLayout position 
buttons according to the order in which they were added, this layout can put 
buttons anywhere as shown by the fact that button “four” is placed before button 
“threethreethree” even though it was added later. 


The CardLayout sample shows how buttons can be displayed across the entire 
width of the container one at a time. Because not all the buttons are visible at the 
same time, the demo implements the DemoButtonListener interface to detect when 
a button is pressed and then show the next button using the show method of 
CardLayout. Note that this is only possible if the string used in the show method 
corresponds to that used in the add method. The button label is the corresponding 
string. 


The NullLayout sample shows that you do not need a Layout manager at all. You 
can place buttons at absolute positions anywhere you want by calling the 
setBounds method. Note, however, that buttons may therefore overlap since it 
obeys the explicit positions you specify. 


The samples look like this: 
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Following is the LayoutDemo sample code: 
import java.awt.*; 
class LayoutDemo extends Demo { 


public LayoutDemo() { 
this (600, 400); 


public LayoutDemo(int width, int height) { 


super (width, height); 

setLayout (new GridLayout (3, 2)); 
add(new FlowLayoutDemo()); 
add(new BorderLayoutDemo () ) ; 
add(new GridLayoutDemo()); 
add(new GridBagLayoutDemo () ); 
add(new CardLayoutDemo()); 
add(new NullLayoutDemo()); 


FlowLayoutDemo Sample 


import java.awt.*; 


class FlowLayoutDemo extends Demo { 
public FlowLayoutDemo() { 
this (300, 200); 


public FlowLayoutDemo(int width, int height) { 
super (width, height); 


setLayout (new FlowLayout ()); 
add(new DemoButton ("one") ); 
add(new DemoButton("2")); 


( ( 
add(new DemoButton("threethreethree") ); 
add(new DemoButton("four")); 
( ( 
( ( 
( ( 


add(new DemoButton("five")); 
add(new DemoButton Raia 
add(new DemoButton("seven") ); 


BorderLayoutDemo Sample 


import java.awt.*; 


class BorderLayoutDemo extends Demo { 
public BorderLayoutDemo() { 
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this (300, 200); 


public BorderLayoutDemo(int width, int height) { 
super (width, height); 
setLayout (new BorderLayout ()); 
add(new DemoButton ("Center"), BorderLayout.CENTER) ; 
add(new DemoButton ("North"), BorderLayout.NORTH) ; 
add(new DemoButton ("South"), BorderLayout.SOUTH) ; 
add(new DemoButton("East"), BorderLayout.EAST) ; 
add(new DemoButton("West"), BorderLayout.WEST) ; 


GridLayoutDemo Sample 


import java.awt.*; 


class GridLayoutDemo extends Demo { 
public GridLayoutDemo() { 
this (300, 200); 


public GridLayoutDemo (int width, 
super (width, height); 


int height) { 


setLayout (new GridLayout (3, 2)); 
add(new DemoButton("one") ); 

add(new DemoButton("2")); 

add(new DemoButton("threethreethree") ); 
add(new DemoButton("four")); 

add(new DemoButton("five")); 

add(new DemoButton("six")); 


GridBagLayoutDemo Sample 


import java.awt.*; 


class GridBagLayoutDemo extends Demo { 
private GridBagLayout gbl; 
private GridBagConstraints gbc; 
public GridBagLayoutDemo() { 
this (300, 200); 


public GridBagLayoutDemo (int width, 
super (width, height); 
gbl = new GridBagLayout (); 


int height) { 
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gbc 


setLayout (gbl); 


= new GridBagConstraints(); 


DemoButton bl new DemoButton ("one"); 

DemoButton b2 = new DemoButton("2"); 

DemoButton b3 = new DemoButton("threethreethree") ; 

DemoButton b4 = new DemoButton("four") ; 

DemoButton b5 = new DemoButton ("five"); 

DemoButton b6 = new DemoButton ("six"); 

DemoButton b7 = new DemoButton("seven"); 

Insets insets = new Insets(0, 0, 0, O); 

add(b1, 0, 0, 1, 1, GridBagConstraints.NONE, 0, 0, insets, 
GridBagConstraints.NORTHWEST, 0.0, 0.0); 

add(b2, 1, 0, 2, 1, GridBagConstraints.NONE, 0, 0, insets, 
GridBagConstraints.NORTHWEST, 0.0, 0.0); 

add(b3, 0, 1, 4, 1, GridBagConstraints.NONE, 0, 0, insets, 
GridBagConstraints.NORTHWEST, 0.0, 0.0); 

add(b4, 2, 0, 1, 1, GridBagConstraints.NONE, 0, 0, insets, 
GridBagConstraints.NORTHWEST, 0.0, 0.0); 

add(b5, 0, 2, 1, 1, GridBagConstraints.BOTH, 0, 0, insets, 
GridBagConstraints.NORTHWEST, 0.0, 0.0); 

add(b6, 1, 2, 1, 1, GridBagConstraints.NONE, 10, 10, insets, 
GridBagConstraints.NORTHWEST, 0.0, 0.0); 

add(b7, 2, 2, 1, 1, GridBagConstraints.NONE, 0, 0, insets, 
GridBagConstraints.SOUTH, 0.0, 0.0); 

} 
private void add(Component component, int gridx, int gridy, 
int gridwidth, int gridheight, int fill, 
int ipadx, int ipady, Insets insets, int anchor, 


double weightx, 
gbc. 
gbc. 
gbc. 
gbc. 
gbc. 
gbc. 
gbc. 
gbc. 
gbc. 


gbc 
gbc 


gbl. 


double weighty) { 


gridx = gridx; 

gridy = gridy; 

gridwidth = gridwidth; 
gridheight = gridheight; 
fill = fill; 

ipadx = ipadx; 

ipady = ipady; 

insets = insets; 

anchor = anchor; 
-weightx = weightx; 
-weighty = weighty; 
setConstraints (component, gbc); 


add (component) ; 


import java. 
import java. 
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CardLayoutDemo Sample 


awt.*; 
util.EventObject; 
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class CardLayoutDemo extends Demo implements DemoButtonListener { 


CardLayout cardLayout = new CardLayout (); 
DemoButton[] bottuns = new DemoButton [] { 
new DemoButton ("one"), 
new DemoButton("2"), 
new iy onesies che ese Ga 
new DemoButton ("four"), 
( 
( 
( 


new DemoButton ("five"), 
new DemoButton ("six"), 
new DemoButton ("seven") 


}; 


public CardLayoutDemo() { 
this (200, 100); 


public CardLayoutDemo(int width, int height) 
super (width, height); 
setLayout (cardLayout) ; 
for (int i = 0; i < bottuns.length; i++) 


bottuns [i] .addDemoButtonListener (this) ; 
add(bottuns[i].getLabel(), bottuns[i]); 


public void buttonPressed(EventObject e) { 


DemoButton b = (DemoButton) e.getSource(); 
for (int i = 0; i < bottuns.length; i++) 


int j =i+ 1; 


if (j == bottuns.length) { 
5207 

} 

if (b == bottuns[i]) { 
b = bottuns[j]; 
break; 


} 
cardLayout.show(this, b.getLabel()); 


NullLayoutDemo Sample 


import java.awt.*; 


class NullLayoutDemo extends Demo { 
public NullLayoutDemo() { 
this(200, 100); 
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public NullLayoutDemo(int width, int height) { 
super (width, height); 
setLayout (null); 
DemoButton bl = new DemoButton ("one"); 
DemoButton b2 = new DemoButton("2"); 
DemoButton b3 = new DemoButton("threethreethree") ; 
DemoButton b4 = new DemoButton("four"); 
DemoButton b5 = new DemoButton ("five"); 
DemoButton b6 = new DemoButton ("six"); 
DemoButton b7 = new DemoButton("seven"); 
add (bl); 
add (b2); 
add (b3); 
add (b4); 
add (b5); 
add (b6) ; 
add (b7); 
bl.setBounds(10, 10, 30, 20); 
b2.setBounds (60, 10, 40, 30); 
b3.setBounds (120, 10, 50, 80); 
b4.setBounds (130, 70, 50, 20); 
b5.setBounds(70, 70, 50, 20); 
b6.setBounds (10, 70, 50, 20); 
b7.setBounds (10, 40, 180, 20); 
} 
} 
ey 


Implementing Security and Permissions 


The security features are basically the same as for the J2SE environment. However, 
the java.policy file that is located in the /build/linux-i686/lib/security 
directory has been changed to allow all applications and applets access to the set of 
properties as specified in the specification under profile-specific properties. Access 
to the keys through the system properities is never security-constrained. 


Working with Threads 


Most deprecated methods were removed from CDC and Foundation Profile (which 
Personal Profile runs over) in order to reduce the size of the implementation and to 
present a clean API. Applications that use deprecated methods will not function 

correctly or may not function at all due to the removal of these methods. However, 
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Personal Profile includes the deprecated methods from java.awt. So it is possible 
to have an application that uses deprecated methods or classes from java. awt 
that will function correctly. 


For example, the java.lang. Thread class methods stop, suspend, and resume 
have been removed. The following documents describe these changes, and also 
how to work around the removal of these methods: 


http://java.sun.com/j2se/1.3/docs/guide/misc/ 
threadPrimitiveDeprecation.html 


http://java.sun.com/docs/books/tutorial/post1.0/preview/ 
threads.html 


The following documents are Swing-specific, but also provide general information 
about GUI ad AWT programming. They deal with the scenario where the program 
creates threads to perform tasks that affect the GUI, or if it manipulates the 
already-visible GUI in response to anything but a standard event: 


http://java.sun.com/docs/books/tutorial/uiswing/overview/ 
threads .html 


http://java.sun.com/products/jfc/tsc/articles/threads/ 
threads1l.html 


http://java.sun.com/docs/books/tutorial/uiswing/misc/ 
threads .html 


Working with JavaBeans 


The Personal Profile API specifies a subset of the java.beans package as found in 
the J2SE Platform. Basically, the API specifies a number of classes that support 
runtime JavaBeans. Some of the classes, interfaces, and exceptions included in the 
Personal Profile java.beans package are also modified as compared with the 
equivalent in the J2SE environment. 


The J2SE Platform provides a number of classes that are meant to be used by a bean 
editor (that is, a development environment for customizing and putting together 
beans to create an application). In particular, these classes help the bean editor 
create a user interface that the user can use to customize the bean. These classes are 
not included in the Personal Profile subset of the java.beans package. 


You can create beans in the J2SE environment, since it has events classes and an 
editor for designing a bean, and you can use the J2SE environment to compile the 
classes. 

The Personal Profile java.beans package contains the following: 


m Interfaces — PropertyChangeListener, VetoableChangeListener, 
Visibility 
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import 
import 
import 


public 


m Classes — Beans, PropertyChangeEvent, PropertyChangeSupport, 
VetoableChangeSupport 


. Exceptions — PropertyVetoException 


See the Personal Profile specification to determine the exact functionality of the 
classes included in the java.beans package. 


Included in the reference implementation is a very simple example of using some 
of the java.beans API included in Personal Profile. Personal Profile contains 
classes to support runtime JavaBeans only. 


The sample contains two classes: ColorBean and ColorBeanTester. When you run it, 
the sample looks like this: 


[= <unknown> [lal] 


ColorBean Sample 


ColorBean is a simple bean that displays a colored rectangle in a container. The 
bean contains the property beanColor which relates to the color of this rectangle. 
The beanColor can be modified through the setColor method. This bean also 
includes an instance of Propert yChangeSupport. Using this class, ColorBean can 
notify any registered listeners of the bean that a property has changed — in this 
case, the beanColor property. 


Following is the sample code: 


java.awt.*; 
java.beans.*; 
java.io.Serializable; 


class ColorBean extends Container implements Serializable { 


PropertyChangeSupport cs; 


public ColorBean() { 
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// Create PropertyChangeSupport instance. 
cs = new PropertyChangeSupport (this); 


public void paint(Graphics g) { 
g.setColor (beanColor) ; 
g.fillRect(10, 10, 110, 110); 


public Color getColor() { 
return beanColor; 


public void setColor(Color newColor) { 
beanColor = newColor; 
// Notify registered listeners of property change event. 
cs.firePropertyChange("beanColor", null, newColor); 
repaint (); 


private Color beanColor = Color.blue; 


ColorBeanTester Sample 


ColorBeanTester is a simple class that creates an instance of 
ColorBean.ColorBeanTester and then registers as a listener of ColorBean 
When the beanColor in ColorBean is changed, ColorBeanTester is notified of the 
property change through the propertyChange method. 


Following is the sample code: 
import java.awt.*; 
import java.beans.*; 


public class ColorBeanTester implements PropertyChangeListener{ 


public static void main(String[] args) { 
ColorBeanTester cbt = new ColorBeanTester(); 
cbt.runit (); 


public void runit() { 
Frame f = new Frame(); 


f.setSize(640, 480); 
f.setResizable (true); 
f.addWindowListener (new WindowAdapter() { 
public void windowClosing(WindowEvent we) { 
f£.dispose(); 
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System.exit (0); 


3 
f.setVisible (true) ; 


try{ 


// Instantiate ColorBean. 
ColorBean bean = (ColorBean) Beans.instantiate (null, 
"ColorBean") ; 


// Register instance of this class as a 
// PropertyChangeListener of ColorBean. 
bean.cs.addPropertyChangeListener (this) ; 


f.add( (Container) bean) ; 
f.validate(); 
f.repaint (); 
Thread.sleep (1000); 


while (true) { 
// Set the beanColor property 
bean.setColor (Color.green) ; 


Thread.sleep (1000); 


// Set the beanColor property 
bean.setColor(Color.red); 


Thread.sleep (1000); 
} 


} catch(Exception ex) {} 


// Notified when a PropertyChangeEvent occurs. 
public void propertyChange (PropertyChangeEvent evt) { 
System.out.printin("Color Property Change Event = + evt); 


More Information on JavaBeans 


The following URLs provide more information on JavaBeans. However, because the 
Personal Profile reference implementation provides a subset of the JavaBeans API 
in the J2SE Platform, these documents may reference some functionality that is not 
included in Personal Profile. See the specification to determine what is included. 
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Technical articles regarding JavaBeans: 


http://developer. java.sun.com/developer/technicalArticles/ 
jbeans/index. html 


Java Tutorial: 
http://java.sun.com/docs/books/tutorial/javabeans/ 
JavaBeans Home Page: 
http://java.sun.com/products/javabeans/ 

JavaBeans Component Architecture: 
http://java.sun.com/products/javabeans/docs/index.html 
Java Developer Connection Training: 


http://developer. java.sun.com/developer/onlineTraining/Beans/ 
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CHAPTER 9 


Using the Reference 
Implementation as a Development 
Platform 


You can use the packages in the Personal Profile reference implementation to 
develop your own applications, applets, Xlets, toolkits, and APIs. (This is an 
alternative to creating your own implementation of Personal Profile based on the 
specification, JSR-62, and developing over it.) 

This chapter contains the following sections about the reference implementation: 
a “Compiling an Application, Applet, or Xlet” on page 179 

a “Running an Application, Applet, or Xlet by Using CVM” on page 180 

a “Debugging an Application, Applet, or Xlet” on page 185 


You should also understand the restrictions of the reference implementation, as 
described in “Implementation Considerations” on page 28. 


See Porting Notes, J2ME™ Personal Profile, Version 1.0 for other important 
information about developing with the reference implementation. 


Compiling an Application, Applet, or 
Xlet 


You can compile Personal Profile applications, applets, and Xlets using the J2SE 
Platform, version 1.3 or later. To compile applications properly so that nonexistent 
classes or methods are not used inadvertently, all you have to do is add a 
-bootclasspath option to the command line and compile as normal using 
javac: 


javac -bootclasspath btclasses.zip:personal.jar app 
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This command line assumes that btclasses.zip and personal. Jar are in 
your currect working directory. app is the Java file you want to compile, including 
the path specification. It is also assumed that you set up your environment so that 
the javac command executes from any directory (without having to specify the 
path to it). 


For example, if your source file is MyApp. java and it’s in the Personal Profile 
installation directory (which is your current working directory), you could use: 
javac -bootclasspath /personal/build/linux-i686/\ 


btclasses.zip:/personal/build/linux-i686/lib/personal.jar\ 
MyApp. java 


Running an Application, Applet, or Xlet 
by Using CVM 


To run a Personal Profile application, applet, or Xlet, you use the C Virtual Machine 
(CVM). To run an applet or Xlet, you also use the Applet Viewer or Xlet Runner, 
respectively. 


CVM is a full-featured Java 2 virtual machine that is designed for higher-end, next 
generation consumer electronic and embedded devices; that is, devices with a 32- 
bit processor and 2Mb+ of total memory. These devices include wireless 
communicators, high-end PDAs (for example, devices running embedded Linux or 
Windows CE), residential gateways, automotive telematic systems, and 
screenphones. 


CVM is provided with CDC. In the Personal Profile reference implementation, 
CVM is located in personal/build/linux-i686/bin of the installation 
directory. To see the complete list of command line options for CVM, enter the cvm 
command without any arguments. See the CDC documentation for complete 
information about CVM and its command-line options. 


Note that when you are packaging your program, CVM can’t be statically linked to 
GTK, as this is a licensing violation. See www. gnu. org for more information. 


Running an Application 


The basic command to execute an application is 


cvm [-Djava.class.path=classpath] className 


This command line assumes that you set up your environment so that the cvm 
command executes from any directory (without having to specify the path to it). 
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classpath is the path or paths that CVM uses to look up classes for the 
application. If more than one path is specified, they must be separated by colons. 
Each path should end with the directory containing the class file(s) to be executed. 
However, if a file to be executed is a ZIP or JAR file, the path to that file must end 
with the file's name. Here’s an example of specifying three paths (including the 
current directory): 


.:/home/xyz/classes:/usr/local/java/classes/MyClasses. jar 
If all the classes are contained in a single directory, you don’t need to specify a 
classpath. CVM will use the current directory, and the directory where the CVM is 


loaded from. You only have to specify the classpath for applications using multiple 
class directories or JAR files. 


className is the fully qualified class name (long name) of the compiled Java class, 
including its package name. 


Following are some examples. 


If your current working directory is personal /build/linux-i686/democlasses 
(in the reference implementation), enter this command line to run the HelloWorld 
sample application: 


../bin/cvm HelloWorld 


Enter this command line to run the IXC sample: 


../bin/cvm IXCDemo.IXCMain 
IXCMain is in the IXCDemo package. 


If the class MyClass is in a package called mypackage, which is in a directory 
called classes, you can use 


cvm —Djava.class.path=classes mypackage.MyClass 


But the following would NOT work: 
cvm -Djava.class.path=classes/mypackage MyClass 
As this example illustrates, you must always use the fully qualified name of the 


class on the command line. The classpath specifies the directories (or archive files) 
where the the top-level package resides. 


For other examples of running applications, see Chapter 2, “Running the Sample 
Programs.” 


Running an Applet 


The reference implementation provides an Applet Viewer to run your applets, as 
described in Chapter 4, “Writing Applets.” The sun. applet .AppletViewer class 
is a simple applet launcher that you can use to run applets that extend the 
java.applet.Applet class. It’s in this location of the reference implementation: 


Chapter9 Using the Reference Implementation as a Development Platform 181 


src/share/personal/classes/common/sun/applet/AppletViewer. java. 
The Applet Viewer is useful for testing your applets. For deployment, you would 
run them in a browser that is compatible with Personal Profile. 


The basic command to execute an applet with the Applet Viewer is 


cvm sun.applet.AppletViewer [-Djava.class.path=classpath] URL 


This command line assumes that you set up your environment so that the cvm 
command executes from any directory (without having to specify the path to it). 
URL is an HTML file with the APPLET tag (or OBJECT or EMBED tags). A URL is a 
Uniform Resource Locator (formerly Universal Resource Locator). It is an Internet 
address which tells a browser where to find an Internet resource. URLs are 
discussed more at: 


http://java.sun.com/docs/books/tutorial/networking/urls/ 
definition.html 


In the case of applets, the resource that the URL points to is the HTML file; the 
HTML file then points to the applet that is to be displayed. The Applet Viewer will 
open each applet it finds on a HTML page in a separate Applet Viewer Frame, so it 
is possible to specify multiple URLs on the command line. 


classpath is the path or paths that CVM uses to look up classes for the 
application. If more than one path is specified, they must be separated by colons. 
Each path should end with the directory containing the class file(s) to be executed. 
However, if a file to be executed is a ZIP or JAR file, the path to that file must end 
with the file's name. Here’s an example of specifying three paths (including the 
current directory): 


.:/home/xyz/classes:/usr/local/java/classes/MyClasses. jar 

The Applet Viewer automatically initializes and starts the applet. The Applet 
Viewer connects to the documents or resources designated by URLs and displays 
each applet referenced by the documents in its own window. If the documents 


referred to by URLs do not reference any applets with the OBJECT, EMBED, or 
APPLET tag, then the Applet Viewer does nothing. 


The Personal Profile reference implementation borrowed the Applet Viewer 
supplied with the J2SE environment. However, it does not support all of the 
command line options, such as -debug, -encoding, and —J, as described at 


http://java.sun.com/j2se/1.3/docs/tooldocs/solaris/ 
appletviewer.html 


It does support the same HTML tags, as described at 
http://java.sun.com/j2se/1.3/docs/tooldocs/appletviewertags.html 


Here are some examples. If your current working directory is personal/build/ 
linux-i686/democlasses (in the reference implementation), enter this command 
line to run the DemoApplet sample: 


../bin/cvm sun.applet.AppletViewer DemoApplet.html 
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In addition, you might want to use other cvm options on the command line. For 
example, the following command line allows the Applet Viewer to view applets on 
the web through the specified proxy and port number, just like a browser might: 


./cvm -—DtrustProxy=true —-Dhttp.proxyHost=myweb.uk.sun.com \ 
—Dhttp.proxyPort=8080 sun.applet.AppletViewer \ 
http://java.sun.com/our-applet.html 


For other examples of running applets, see Chapter 2, “Running the Sample 
Programs.” 


Running an Xlet 


The reference implementation provides the Xlet Runner to run your Xlets, as 
described in “A Simple Xlet Manager” on page 74. It is located in src/share/ 
personal/classes/common/com/sun/xlet. 


The com.sun.xlet .XletRunner class is a simple Xlet launcher that you can use 
to run Xlets that implement the javax.microedition.xlet.Xlet interface. You 
can use this Xlet Runner, or write your own. 


The basic command to execute an Xlet with the Xlet Runner is 


cvm com.sun.xlet.XletRunner -name XletName -path XletPath 


The Xlet Runner automatically initializes and starts the Xlet. This command line 
assumes that you set up your environment so that the cvm command executes from 
any directory (without having to specify the path to it). 


There are five options that the Xlet Runner takes: 


m -name XletName 


Mandatory. The short name of the compiled Java class that implements the 
interface javax.microedition.xlet.Xlet 


m -path XletPath 


Mandatory (or substitute with the codebase option). The path to the Xlet, 
absolute or relative to the current directory; for example, . /MyFiles. If the Xlet 
is in a JAR (or another type of archive file), include the archive filename; for 
example, 

./MyFiles/MyXlet. jar. 


m -args argl [arg2] [arg3] 


Optional. Runtime arguments you want to pass to the Xlet through the 
XletContext. Multiple arguments are separated by a space. For example, if you 
run MyXlet with this command line 


cvm com.sun.xlet.XletRunner -name MyXlet -path . -args top 
bottom right 


Then calling XletContext .getXletProperty (XletContext.ARGS) in 
MyXlet would return an array of Strings of length 3 and containing the values 
top, bottom, and right. 
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-filename filename 


Optional. A file containing any of the other command line options. The file must 
be in text file format, but a txt extension is not required on the command line. 
This option redirects the Xlet Runner to read the options from a file rather than 
from the command line. The -f£i1lename option should be the first option 
provided to the Xlet Runner, or else the Xlet Runner would ignore the option or 
exit with a warning that the syntax is not correct. For example, the following 
command line will start MyXlet and ignore what is in the file test: 


cvm com.sun.xlet.XletRunner -name MyXlet -path /home/cs/testxlets 
-filename test 


The following will not run anything: 


cvm com.sun.xlet.XletRunner -name MyXlet -filename test 


The next command line will run whatever is in the file test and ignore MyXlet: 


cvm -filename test -name MyXlet -path /home/cs/testxlets 
-codebase URL_path 
Optional. The path used to load an Xlet over a URL. You can substitute the path 


option with codebase, and provide a URL-formatted path instead of the file 
path. For example, the following command line 


cvm com.sun.xlet.XletRunner -name MyXlet -codebase http:// 
java.sun.com/xlets/demo 


tells the Xlet Runner to load the Xlet whose compiled code is at the URL http: / 
/java.sun.com/xlets/demo/MyXlet.class. 


So the more complete command line syntax would be 


cvm com.sun.xlet.XletRunner {-name XletName {-path XletPath 


or 


-codebase URL_path} [-args argl [arg2] [arg3] ...]} 


cvm com.sun.xlet.XletRunner -filename filename 


Note — The Xlet MUST NOT be found in the system classpath, especially when 
running more than one Xlet, because by definition Xlets should be loaded by a 
separate ClassLoader. If an Xlet is found in the system classpath, the system 
ClassLoader loads it instead of the correct one. 


For example, to run StockTickerXlet in a JAR file named xlet . jar with the 
arguments colorMap and blue, use the following command line: 


cvm com.sun.xlet.XletRunner -name StockTickerXlet -path xlet.jar \ 


-args colorMap blue 


The following command line would also work: 


cvm com.sun.xlet.XletRunner -filename argfile 


if argfile includes the line: 


-name StockTickerXlet -path xlet.jar -args colorMap blue 
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To run more than one Xlet, repeat the Xlet Runner options, for example: 


cvm com.sun.xlet.XletRunner -name ServerXlet -path ./server -name \ 
ClientXlet -path ./client 


For more examples of running Xlets with the Xlet Runner, see Chapter 2, “Running 
the Sample Programs.” 


Debugging an Application, Applet, or 
Xlet 


You can debug an application, applet, or Xlet using the J2SE Platform, version 1.3 
or later. If the program does work with the J2SE Platform, but doesn’t work with 
Personal Profile, you can create a debug version of CVM, attach a debugger to it, 
and debug your program in Personal Profile; see the release notes for instructions. 
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CHAPTER 1 0 


Comparing Personal Profile and the 
PersonalJava Environment 


This chapter compares Personal Profile reference implementation and the reference 
implementation of the PersonalJava environment and outlines some important 
differences. It is particularly useful to programmers familiar with the PersonalJava 
environment and who want to migrate to Personal Profile. The chapter has the 
following sections: 


“New Features in Personal Profile” on page 188 


“Ttems that Aren’t Supported or Are Partially Supported” on page 189 


“Reference Implementation Platforms Comparison” on page 189 


“Package Comparison” on page 190 


“Unsupported, Deprecated Methods in the PersonalJava Environment” on 


page 194 


Note that this chapter does not compare the Foundation Profile packages that 
Personal Profile uses, including 


java.io 
java.lang 


java.lang.ref 


java.net 


java.security 


java.text 


java.util 


java.util.jar 


java.security. 
java.security. 
java.security. 


java.security. 


java.lang.reflect 


acl 
cert 
interfaces 


spec 
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java.util.zip 


javax.microedition.io 


New Features in Personal Profile 


Some notable new features in Personal Profile, that weren’t included in the 
PersonalJava environment, are the following items. All of the java packages are 
J2SE classes (or subsets of them), but the javax classes are new to Personal Profile. 


java.awt .Color — Alphablending is supported. Every color has an implicit 
alpha value of 1.0 or an explicit one provided in the constructor. The alpha value 
defines the transparency of a color and can be represented by a float value in the 
range 0.0 - 1.0 or 0 - 255. An alpha value of 1.0 or 255 means that the color is 
completely opaque and an alpha value of 0 or 0.0 means that the color is 
completely transparent. Note that the reference implementation doesn’t support 
alphablending, but another implementation might support it. 


java.awt.image.BufferedImage — The BufferedImage subclass describes 
an image with an accessible buffer of image data. 


javax.microedition.xlet and javax.microedition.xlet.ixc — The 
packages provide Xlet support. They contain interfaces used by Xlets and the 
Xlet Manager to communicate. The central function of this set of interfaces is to 
model and manage the states an Xlet can be in. This interface allows an 
application manager to initialize, start, pause, and destroy an Xlet. 


java.awt.GraphicsConfiguration — The GraphicsConfiguration class 
describes the characteristics of a graphics destination, such as a printer or 
monitor. There can be many GraphicsConfiguration objects associated with 
a single graphics device, representing different drawing modes or capabilities. 
The corresponding native structure varies from platform to platform. 


java.awt.GraphicsDevice — The GraphicsDevice class describes the 
graphics devices that might be available in a particular graphics environment. 
These include screen and printer devices. Note that there can be many screens 
and many printers in an instance of GraphicsEnvironment. Each graphics 
device has one or more GraphicsConfiguration objects associated with it. 
These objects specify the different configurations in which the 
GraphicsDevice can be used. 


java.awt.GraphicsEnvironment — The GraphicsEnvironment class 
describes the collection of GraphicsDevice objects and Font objects available 
to a Java application on a particular platform. The resources in this 
GraphicsEnvironment might be local or on a remote machine. 
GraphicsDevice objects can be screens, printers, or image buffers and are the 
destination of Graphics2D drawing methods. Each GraphicsDevice has a 
number of GraphicsConfiguration objects associated with it. These objects 
specify the different configurations in which the GraphicsDevice can be used. 
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java.awt.event.InvocationEvent — An event which executes the run 
method on a Runnable interface when dispatched by the AWT event dispatcher 
thread. This class can be used as a reference implementation of Act iveEvent 
rather than declaring a new class and defining dispatch. Instances of this class 
are placed on the EventQueue by calls to invokeLater and invokeAndWait. 
Client code can use this fact to write replacement functions for invokeLater 
and invokeAndWait without writing special-case code in any 
AWTEventListener objects. 


Items that Aren’t Supported or Are 
Partially Supported 


The PersonalJava environment included the following items, which aren’t included 
in Personal Profile: 


Truffle — For the PersonalJava environment, the peer implementation in Java is 
known as Truffle. The windows toolkit and graphics system support provided 
by Truffle is not covered by the Personal Profile specification and hence is not 
supported in the reference implementation. 


java.awt.PrintGraphics interface 

java.awt.PrintJob class 

java.awt.Peer package — This package was reimplemented in 
sun.awt .peer for toolkit porting. 


java.rmi and java.rmi.registry packages — This API set is addressed in 
RMI OP. However, some of the APIs are reused for IXC, which is similar to RMI 
but communication is between Xlets using the same VM, as described in 
“Implementing Inter-Xlet Communication (IXC)” on page 57. 


com. sun packages — These packages were public in JDK 1.1.8, but were made 
private in subsequent releases. The PersonalJava environment was largely based 
on JDK 1.1.8, so these packages are still present. 


In addition, java.beans is partially supported in Personal Profile, as described in 
“Working with JavaBeans” on page 173. 


Reference Implementation Platforms 
Comparison 


The reference implementation for the PersonalJava environment ran on Windows 
(x86) and Solaris/Sparc, optionally using the Windows and Motif native graphics 
libraries. 
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The Personal Profile reference implementation runs on Red Hat Linux (x86), 


version 7.2. 


Personal Profile uses the Gnome Tookit (GTK+) as its native graphics library. GTK+ 
is a multi-platform toolkit for creating graphical user interfaces, primarily designed 
for the X Window System. For more information, see 


http://www.gtk.org/ 


Package Comparison 


The following table compares the PersonalJava environment to Personal Profile. As 
mentioned earlier, it does not compare the Foundation Profile packages. 


Item 


Personal Java Application 
Environment (PJAE), Version 1.2 
PersonalJava, Version 3.1.1 


Personal Profile, Version 1.0 


JDK 


java.applet 


java.awt 


JDK 1.1.8, and Java 2 security 


JDK 1.1.8 APIs fully 
supported 


JDK 1.1.8 modified package 
plus AWTPermission (from 
JDK 1.2.2) 


J2SE Platform, version 1.3.1 (Note: some 
deprecated APIs not included) 


JDK 1.1.8 APIs fully supported, so there are no 
differences between the java.applet package in 
Personal Profile and the PersonalJava 
environment. 

Note that Personal Profile applets use the JDK 1.2 
security model. 


Removed PrintGraphics and PrintJob. 

Added ActiveEvent, GraphicsConfiguration, 
GraphicsDevice and GraphicsEnvironment. 

See the the Javadoc of individual classes for more 
changes. 
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Item 


Personal Java Application 
Environment (PJAE), Version 1.2 
PersonalJava, Version 3.1.1 


Personal Profile, Version 1.0 


java.awt. 
datatransfer 


java.awt.event 


JDK1.1.8 APIs fully supported 


JDK1.1.8 APIs fully supported 


Modified Class: 
java.awt.datatransfer.DataFlavor 
Newly deprecated field: 

plainTextFlavor 

New constuctor: 

DataFlavor () 

Newly deprecated methods: 
normalizeMimeType (java.lang.String 
mimeType) 
normalizeMimeTypeParameter (java. 
lang.String 

parameterName, java.lang.String 
parameterValue) 

New methods: 

clone () 

equals (java.lang.Object 0) 
hashCode () 

match (DataFlavor that) 
readExternal (java.io.ObjectInput is) 
toString () 

writeExternal (java.io.ObjectOutput 
Os) 


New Interfaces /Classes: 
java.awt.event .AWTEventListener 
java.awt.event.InvocationEvent 
Modified Classes: 
java.awt.event.InputEvent 

New Field: 
ALT_GRAPH_MASK 

New Method: 
isAltGraphDown () 
java.awt.event .KeyEvent 
New Fields: 

VK_AGAIN 
VK_ALL_CANDIDATES 


VK_UNDO 
New Method: 


setSource (java.lang.Object newSource) 
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Item 


Personal Java Application 
Environment (PJAE), Version 1.2 
PersonalJava, Version 3.1.1 


Personal Profile, Version 1.0 


java.awt.image 


java.awt.peer 


java.beans 


java.rmi 


java.rmi.dge 


JDK1.1.8 APIs fully supported 


JDK1.1.8 APIs fully supported 
JDK1.1.8 APIs fully supported 


Optional: all of JDK1.1.8 or 
nothing 


Optional 


New Interfaces /Classes: 
java.awt.image.BufferedImage 
Modified Classes: 
java.awt.image.ColorModel 
New Methods: 

hasAlpha () 

hashCode () 
isAlphaPremultiplied () 
toString () 
java.awt.image.DirectColorModel 
New Method: 

toString () 
java.awt.image.IndexColorModel 
New Methods: 

finalize() 

toString () 


Not included 


Unsupported Interfaces/Classes from the 
PersonalJava environment: 
java.beans.BeanInfo 
java.beans.Customizer 
java.beans.PropertyEditor 
java.beans.BeanDescriptor 
java.beans.EventSetDescriptor 
java.beans.FeatureDescriptor 
java.beans.IndexedPropertyDescriptor 
java.beans.Introspector 
java.beans.MethodDescriptor 
java.beans.ParameterDescriptor 
java.beans.PropertyDescriptor 
java.beans.PropertyEditorManager 
java.beans.PropertyEditorSupport 
java.beans.SimpleBeanInfo 

Modified Class: 

java.beans.Beans 

Unsupported Methods from the PersonalJava 
environment: 

getInstanceOf (Object, Class) 
isInstanceOf (Object, Class) 
setDesignTime (boolean) 
setGuiAvailable (boolean) 
Unsupported Exception from the PersonalJava 
environment: 

IntrospectionException 


Supported by RMI OP, an optional API. The RMI 
package in Personal Profile is for IXC support, so 
some pieces are missing. 


Not included 
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Personal Java Application 
Environment (PJAE), Version 1.2 


Item PersonalJava, Version 3.1.1 Personal Profile, Version 1.0 

java.rmi.registry Optional Unsupported Interfaces and Classes 
java.rmi.RegistryHandler 
java.rmi.LocateRegistry 

java.rmi.server Optional Not included 

javax.microedition Not supported Included 

-xlet 

javax.microedition Not supported Included 


.xlet.ixc 
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Unsupported, Deprecated Methods in 
the PersonalJava Environment 


The following methods are not present in Personal Profile. 


Class Method 


java.awt.Component action(Event evt, java.lang.Object 
what) bounds () 
deliverEvent (Event e) 
disable () 
enable () 
enable (boolean b) 
getPeer () 
gotFocus (Event evt, java.lang.Object 
what) 
handleEvent (Event evt) 
hide () 
inside(int x, int y) 
keyDown (Event, int) 
keyUp (Event, int) 
layout () 
locate(int, int) 
location () 
lostFocus (Event, Object) 
minimumSize () 
mouseDown (Event, int, int) 
mouseDrag(Event, int, int) 
mouseEnter(Event, int, int) 
mouseExit (Event, int, int) 
mouseMove (Event, int, int) 
mouseUp (Event, int, int) 
move(int, int) 
nextFocus () 
postEvent (Event) 
preferredSize() 
reshape(int, int, int, int) 
resize (Dimension) 
resize(int, int) 
show () 
show (boolean) 
size() 
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Class 


Method 


java.awt.Container 


java. 


java. 


java. 


java. 


java. 


-awt 


-awt 


awt 


awt 


awt 


awt 


-awt 


awt 


-FontMetrics 


. Frame 


.Graphics 


-MenuComponent 


.-MenuContainer 


-Polygon 


-Rectangle 


.Window 


countComponents () 
deliverEvent (Event) 
getInsets () 
layout () 
locate(int, int) 
minimumSize () 
preferredSize() 


getMaxDecent () 


getCursorType () 
setCursor (int cursorType) 


getClipRect () 


getPeer () 
postEvent (Event evt) 


postEvent (Event evt) 


get BoundingBox () 
inside(int, int) 


inside(int x, int y) 

move(int x, int y) 

reshape(int x, int y,int width, 
int height) 

resize(int width,int height) 


postEvent (Event) 
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AlphaComposite class, restrictions, 98 
animation, 149 
Animator sample, 15 
applets 
applet lifecycle, 38 
APPLET tag in HTML page, 35 
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Xlet Manager, 78 
Xlet Runner, 75 


B 
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C 
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CDC 
description, 6 
more information about, xiii 
specification, xiii 
Color sample, 14 
color, working with, 131 
ColorBean sample, 14 
Component class, restrictions, 98 
components, creating, 123 


Connected Device Configuration, See CDC 


Cursor sample, 16 
cursors, 154 
CVM, 107 


D 


DASE, 3 
DemoApplet sample, 13 
demos, See samples 


deprecated methods, 29, 173, 190, 194 


Dialog class, restrictions, 98 
Draw sample, 15 


E 


events 
components, 127 


publishing and subscribing to, 162 


F 


FlowLayout sample, 17 
Font sample, 15 
FontMetrics sample, 16 
fonts, 150 
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Foundation Profile java.applet package, 95 
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specification, xiii java.awt.datatransfer package, 96 
FrameDemo sample, 14 java.awt.event package, 96 
Frames java.awt.image package, 96 
restrictions, 98 java.beans package, 96 
sample illustrating behavior differences, 120 java.rmi package, 97 
Xlets, 47 java.rmi.registry package, 97 
JavaBeans, 173 
G javax.microedition.xlet package, 97 
javax.microedition.xlet.ixc package, 97 
graphics, 139 JSRs, xii 
Graphics2D class, restrictions, 98 
GridBagLayout sample, 17 K 
GridLayout sample, 17 
GTK Keyboard sample, 16 
more information about, xiii KeyEvents, 162 
reference implementation use, 10 KeyEvents sample, 16 
H | 
HAVi, 3 layout managers, 167 
HelloWorld sample, 13 Layout samples, 17 
I M 
I/O reading and writing, 107 methods, deprecated removed, 29 
Image sample, 15 MHP, 3 
images, 139 microedition packages, 45 
Inter-Xlet Communication, See IXC J2SE environment compatibility issue, 29 
isRestricted property, 30 Mouse sample, 16 
IXC 
comparison to RMI, 57 N 
sample, 13, 57 
state changes, 56 NullLayout sample, 17 


Xlet Runner considerations, 20 


O 


J OCAP, 3 
J2ME Platform, xi online Sun documentation, xvi 
specification, xiii 
website, xiii P 
J2SE Platform, xiii 
compatibility with Personal Basis Profile packages, Personal Profile, 95 
applications, 29 Personal Profile 
Java Community Process, xiv additional functionality over Personal Basis 
Java literature, xiv Profile, 2 
Java Specification Requests, xii specification, xiii 
Java TV PersonalJava environment, comparison with 
more information about, xiv Personal Profile, 187 
relationship to Personal Profile, 3 Portable Operating Systems Interface, xiv 
POSIX, xiv 
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PPDemo sample, 14 

properties 
AppletContext, 38 
specifying Component restrictions, 30 
XletContext, 46 


R 


reference implementation, developing with, 10, 
179 

Remote Method Invocation Optional Package, See 
RMI OP 

RMI OP 
description, 6 
specification, xiii 


S 


samples 

descriptions, 13 

running, 13 

Xlet Manager, 78 
setEchoChar method, restrictions, 99 
SimpleXletDemo sample, 13 
specification, Personal Profile, xiii 
supportLevel property, 30 
supportMask property, 30 
system resources, accessing, 108 
SystemColor sample, 14 


T 
threads, 173 


U 


UNIX commands, xv 


V 


virtual machine, See VM 
VMs 

used for IXC, 57 

Xlet Manager usage, 9 


W 
Widget sample, 17 
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Xlet Managers 
managing states, 50 
requirements, 73 
sample, 74, 78 

Xlet Runner, 74 
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sample, 75 
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application model, 8 
basic functions, 41 
comparison with applets, 9 
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compiling, 179 
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destroying, 49, 51 
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initializing, 46, 50 
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